@vellumai/assistant 0.12.2-dev.202609181819.66f51a7 → 0.12.2-dev.202609182015.188de8a

package/ARCHITECTURE.md

@@ -96,7 +96,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Credential storage:** Only hashed tokens are persisted. Access token hashes go in `credential_records`; refresh token hashes in `refresh_token_records`. Raw tokens are returned once and never stored server-side.
 
-**Notification scoping:** Guardian-sensitive notifications are annotated with `targetGuardianPrincipalId` for identity-scoped delivery.
+**Notification scoping:** Guardian-sensitive notifications (`notification_intent`, `notification_conversation_created`) are published with `targetActorPrincipalId`, so the event hub delivers them, live, on reconnect replay, and from the `events/tail` recovery route, only to SSE connections whose verified `actorPrincipalId` is the guardian's. Connections without a principal never receive them. The payload's `targetGuardianPrincipalId` records the scoping.
 
 **Key source files:**
 
@@ -289,32 +289,35 @@ The WhatsApp channel enables inbound and outbound messaging via the Meta WhatsAp
 
 **Ingress** (`GET /webhooks/whatsapp` — verification, `POST /webhooks/whatsapp` — messages):
 
-1. **Webhook verification**: Meta sends a `GET` with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`. The gateway compares `hub.verify_token` against `WHATSAPP_WEBHOOK_VERIFY_TOKEN` and echoes `hub.challenge` as plain text.
-2. On `POST`, the gateway verifies the `X-Hub-Signature-256` header (HMAC-SHA256 of the raw request body using `WHATSAPP_APP_SECRET`) when the app secret is configured. Fail-closed: requests are rejected when the secret is set but the signature fails.
+1. **Webhook verification**: Meta sends a `GET` with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`. The gateway compares `hub.verify_token` against the `webhook_verify_token` credential and echoes `hub.challenge` as plain text.
+2. On `POST`, the gateway verifies the `X-Hub-Signature-256` header (HMAC-SHA256 of the raw request body using the `app_secret` credential). Fail-closed: a request is rejected with 500 when no app secret is configured, and with 403 when the signature does not match.
 3. **Normalization**: Text and media messages (image, audio, video, document, sticker) from `messages` change fields are forwarded. Delivery receipts, read receipts, and unsupported message types (contacts, location) are silently acknowledged with `{ ok: true }`. Media attachments are downloaded from the WhatsApp Cloud API, uploaded to the runtime attachment store, and their IDs are passed alongside the message content.
 4. **`/new` command**: When the message body is `/new` (case-insensitive), the gateway resolves routing, resets the conversation, and sends a confirmation message without forwarding to the runtime.
 5. The payload is normalized into a `GatewayInboundEvent` with `sourceChannel: "whatsapp"` and `conversationExternalId` set to the sender's WhatsApp phone number (E.164).
 6. WhatsApp message IDs are deduplicated via `StringDedupCache` (24-hour TTL).
 7. The gateway marks each inbound message as read (best-effort, fire-and-forget).
-8. The event is forwarded to the runtime via `POST /channels/inbound` with WhatsApp-specific transport hints and a `replyCallbackUrl` pointing to `/deliver/whatsapp`.
+8. The event is forwarded to the runtime via `POST /channels/inbound` with WhatsApp-specific transport hints and a `replyCallbackUrl` of `<gatewayInternalBaseUrl>/deliver/whatsapp`. The gateway serves no route at that path: the daemon uses the URL only to address the reply (see Egress).
 
-**Egress** (`POST /deliver/whatsapp`):
+**Egress** (daemon WhatsApp transport, `src/messaging/providers/whatsapp/`):
 
-1. The runtime calls the gateway's `/deliver/whatsapp` endpoint with `{ to, text }` or `{ chatId, text }` (alias).
-2. The gateway authenticates the request via bearer token (same fail-closed model as other deliver endpoints).
-3. The gateway sends the message via the WhatsApp Cloud API `/{phoneNumberId}/messages` endpoint using the configured access token.
-4. Text is split at 4096 characters if needed.
+1. Replies, approval prompts, and proactive sends go out through the daemon's `whatsappTransport` (`transport.ts`), which calls the Meta Cloud API itself. `isDirectDelivery()` in `src/messaging/providers/index.ts` resolves the `/deliver/whatsapp` callback URL to this transport through `channelForCallback()` (`src/messaging/providers/callback-routing.ts`), so the daemon never posts back to the gateway or dials the URL's host and port. The gateway's own replies to invite and verification codes it intercepts at ingress reach this transport the same way: `deliverVerificationReply` (`gateway/src/verification/reply-delivery.ts`) hands the reply and the inbound message's callback URL to the daemon's IPC-only `deliver_gateway_reply` method (`src/ipc/routes/channel-reply-ipc-routes.ts`), which resolves the transport from that URL.
+2. `api.ts` reads `phone_number_id` and `access_token` from the secure store and sends through the Cloud API `/{phoneNumberId}/messages` endpoint.
+3. `send.ts` splits text into 4096-character chunks, preferring newline and then whitespace boundaries.
+4. An approval prompt renders as an interactive message with up to three reply buttons whose ids follow the shared `apr:<requestId>:<action>` convention. When the cap forces a cut, the reject and block actions are kept. The gateway normalizes the guardian's `button_reply` back into callback data on ingress.
+5. Attachments up to 25 MB are uploaded to the Cloud API media endpoint and sent as image, video, or document messages. Any that fail are listed in a follow-up text notice.
 
-**Required credentials**:
+The gateway sends only its own notices to WhatsApp (the `/new` confirmation and routing-rejection notices), through `gateway/src/whatsapp/send.ts`.
 
-- `WHATSAPP_PHONE_NUMBER_ID` — the numeric WhatsApp Business phone number ID from Meta
-- `WHATSAPP_ACCESS_TOKEN` — System User or temporary access token
-- `WHATSAPP_APP_SECRET` — App secret for webhook signature verification
-- `WHATSAPP_WEBHOOK_VERIFY_TOKEN` — Token for the Meta webhook subscription handshake
+**Required credentials** (credential vault, `whatsapp` service):
 
-These can be set via environment variables or stored in the credential vault (CES / encrypted store) under the `whatsapp` service prefix.
+- `phone_number_id`: the numeric WhatsApp Business phone number ID from Meta
+- `access_token`: System User or temporary access token
+- `app_secret`: app secret for webhook signature verification
+- `webhook_verify_token`: token for the Meta webhook subscription handshake
 
-**Limitations (v1)**: Rich approval UI (inline buttons) is not supported. Contacts and location message types are acknowledged but not forwarded.
+The daemon reads `phone_number_id` and `access_token` to send. The gateway reads all four: the last two for ingress, and the first two for its own notices.
+
+**Limitations**: Contacts and location message types are acknowledged but not forwarded.
 
 **Channel Readiness**: The channel readiness HTTP endpoints (`GET /v1/channels/readiness`, `POST /v1/channels/readiness/refresh`) backed by `ChannelReadinessService` in `src/runtime/channel-readiness-service.ts` provide a unified readiness subsystem for all channels. Each channel registers a `ChannelProbe` that runs synchronous local checks (credential presence, ingress config) and optional async remote checks with a 5-minute TTL cache. Built-in probes: Telegram (bot token, webhook secret, ingress). The GET endpoint returns cached snapshots; the refresh endpoint invalidates the cache first. Unknown channels return `unsupported_channel`. Route handlers live in `src/runtime/routes/channel-readiness-routes.ts`.
 
@@ -1993,7 +1996,7 @@ An SSE push event surfaces new conversations in the macOS client sidebar:
 
 - **`notification_conversation_created`** — Emitted by `broadcaster.ts` when a notification delivery **creates** a new vellum conversation (strategy `start_new_conversation`, `createdNewConversation: true`). **Not** emitted when a conversation is reused. Payload: `{ conversationId, title, sourceEventName }`.
 
-The event follows this pattern: the daemon creates a server-side conversation, persists an initial message, and broadcasts the SSE event so the macOS `ConversationManager` can create a visible conversation in the sidebar.
+The daemon persists the conversation and its initial message before broadcasting, so a client that receives the event can fetch the conversation immediately. A guardian-sensitive conversation is announced only to the guardian's own connections.
 
 ### Conversation Routing Decision Flow
 
@@ -2031,12 +2034,15 @@ Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `
 
 ### Channel Delivery
 
-Notifications are delivered to three channel types:
+Notifications are delivered to five channel types. The daemon sends to external channels itself, calling each provider's API through the send modules in `src/messaging/providers/<channel>/`; nothing goes through the gateway.
 
 - **Vellum (always connected)**: SSE via the daemon's broadcast mechanism. The `VellumAdapter` emits a `notification_intent` message with rendered copy and optional `deepLinkMetadata` (includes `conversationId` for conversation navigation and `messageId` for message-level scroll anchoring).
-- **Telegram (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/telegram` endpoint. Requires an active guardian binding for the assistant.
+- **Platform (always connected)**: the `PlatformPushAdapter` posts the notification to the platform's `/v1/assistants/{id}/push/dispatch/` endpoint for native mobile push. Without platform credentials the delivery is recorded as failed.
+- **Telegram (when the guardian has a chat ID)**: the `TelegramAdapter` calls the Telegram Bot API through `telegram-bot/send.ts`. Approval cards carry inline keyboard buttons and fall back to plain text with typed-reply instructions if the rich send fails.
+- **Slack (when the guardian's chat is a DM)**: the `SlackAdapter` posts through `slack/send.ts`. Only `D`-prefixed DM channels qualify, so a binding made from a shared channel never receives notifications.
+- **Discord (when the guardian binding names a user)**: the `DiscordAdapter` opens the guardian's DM through the Discord REST API and sends through `discord/send.ts`.
 
-Connected channels are resolved at signal emission time: vellum is always included, and binding-based channels (Telegram) are included only when an active guardian binding exists for the assistant.
+Connected channels are resolved at signal emission time by `getConnectedChannels()` in `emit-signal.ts`, from the guardian delivery list (`getGuardianDelivery()`): vellum and platform are always included, and Telegram, Slack, and Discord are included only when that list gives the guardian a deliverable endpoint on the channel.
 
 **Key modules:**
 
@@ -2050,8 +2056,11 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/notifications/conversation-pairing.ts`                      | Materializes conversation + message per delivery; executes conversation reuse decisions                                               |
 | `assistant/src/notifications/conversation-candidates.ts`                   | Builds per-channel candidate set of recent conversations for the decision engine                                                      |
 | `assistant/src/notifications/adapters/macos.ts`                            | Vellum adapter — broadcasts `notification_intent` via SSE with deep-link metadata                                                     |
-| `assistant/src/notifications/adapters/telegram.ts`                         | Telegram adapter — POSTs to gateway `/deliver/telegram`                                                                               |
-| `assistant/src/notifications/destination-resolver.ts`                      | Resolves per-channel endpoints (vellum SSE, Telegram chat ID from guardian binding)                                                   |
+| `assistant/src/notifications/adapters/platform.ts`                         | Platform adapter: posts to the platform push-dispatch endpoint for native mobile push                                                 |
+| `assistant/src/notifications/adapters/telegram.ts`                         | Telegram adapter: calls the Telegram Bot API through `messaging/providers/telegram-bot/send.ts`                                       |
+| `assistant/src/notifications/adapters/slack.ts`                            | Slack adapter: posts to the guardian's DM through `messaging/providers/slack/send.ts`                                                 |
+| `assistant/src/notifications/adapters/discord.ts`                          | Discord adapter: sends to the guardian's DM through `messaging/providers/discord/send.ts`                                             |
+| `assistant/src/notifications/destination-resolver.ts`                      | Resolves per-channel endpoints from the guardian delivery list (Telegram and Slack chat ID, Discord user ID)                          |
 | `assistant/src/notifications/copy-composer.ts`                             | Template-based fallback copy when LLM copy is unavailable                                                                             |
 | `assistant/src/notifications/preference-extractor.ts`                      | Detects preference statements in conversation messages                                                                                |
 | `assistant/src/notifications/preferences-store.ts`                         | CRUD for user notification preferences                                                                                                |

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -24,13 +24,15 @@ export {
   PersistentIpcClient,
 } from "./ipc-client.js";
 
-// Outbound delivery contract (daemon → gateway) — Zod schemas + derived types
+// Outbound delivery contract: Zod schemas + derived types
 export {
   ApprovalActionOptionSchema,
   ApprovalUIMetadataSchema,
   AttachmentMetadataSchema,
   ChannelDeliveryResultSchema,
   ChannelReplyPayloadSchema,
+  DELIVER_GATEWAY_REPLY_IPC_METHOD,
+  GatewayReplyRequestSchema,
   MessageAudienceSchema,
   PermissionRequestDetailsSchema,
   StreamOpSchema,
@@ -45,6 +47,7 @@ export type {
   AttachmentMetadata,
   ChannelDeliveryResult,
   ChannelReplyPayload,
+  GatewayReplyRequest,
   MessageAudience,
   PermissionRequestDetails,
   StreamOp,

package/node_modules/@vellumai/gateway-client/src/outbound-contract.ts

@@ -1,13 +1,17 @@
 /**
- * Daemon → gateway outbound delivery contract.
+ * Outbound channel delivery contract.
  *
- * Zod schemas defining the wire format for channel replies delivered from
- * the daemon to the gateway via `POST /deliver/{channel}`. Both services
- * import from here so the contract is enforced at compile time.
+ * Zod schemas for a reply to a channel chat. The daemon constructs these
+ * payloads in `deliverChannelReply()` and `deliverApprovalPrompt()` and hands
+ * them to the channel transport its callback URL names
+ * (`messaging/providers`). `/deliver/{channel}` is only that callback URL's
+ * addressing form: no service serves it. A callback URL no
+ * transport owns (a managed callback carrying a `callback_token`) is POSTed
+ * over HTTP by `http-delivery.ts` instead.
  *
- * The daemon constructs these payloads in `deliverChannelReply()` and
- * `deliverApprovalPrompt()`; the gateway validates and dispatches them
- * to the target channel provider.
+ * The gateway sends through the same transports, never to a provider itself:
+ * a reply it composes for a message it answered at ingress goes to the daemon
+ * as a {@link GatewayReplyRequest}.
  */
 
 import type { KnownBlock } from "@slack/types";
@@ -279,6 +283,33 @@ export const ChannelReplyPayloadSchema = z.object({
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;
 
+// ---------------------------------------------------------------------------
+// Gateway reply: gateway to daemon
+// ---------------------------------------------------------------------------
+
+/**
+ * Daemon IPC method that delivers a {@link GatewayReplyRequest}. IPC-only:
+ * it has no HTTP route.
+ */
+export const DELIVER_GATEWAY_REPLY_IPC_METHOD = "deliver_gateway_reply";
+
+/**
+ * A text reply the gateway composed for an inbound message it answered
+ * itself (a verification code, an invite redemption), which the daemon
+ * delivers through the channel transport `callbackUrl` names. The callback
+ * URL is the one the inbound message carried, so the reply lands in the chat
+ * and thread the person wrote from.
+ */
+export const GatewayReplyRequestSchema = ChannelReplyPayloadSchema.pick({
+  chatId: true,
+  assistantId: true,
+}).extend({
+  callbackUrl: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export type GatewayReplyRequest = z.infer<typeof GatewayReplyRequestSchema>;
+
 // ---------------------------------------------------------------------------
 // Channel delivery result — gateway response
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609181819.66f51a7",
+  "version": "0.12.2-dev.202609182015.188de8a",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-event-hub-targeted.test.ts

@@ -257,3 +257,53 @@ describe("AssistantEventHub — getClientById()", () => {
     expect(hub.getClientById("client-x")).toBeUndefined();
   });
 });
+
+// ── Principal targeting ───────────────────────────────────────────────────────
+
+describe("AssistantEventHub principal targeting (targetActorPrincipalId)", () => {
+  test("delivers only to clients authenticated as that principal", async () => {
+    const hub = new AssistantEventHub();
+    const received: Record<string, number> = {
+      guardianMac: 0,
+      guardianWeb: 0,
+      otherUser: 0,
+      noPrincipal: 0,
+      process: 0,
+    };
+    const client = (
+      clientId: string,
+      key: string,
+      actorPrincipalId: string | undefined,
+    ) =>
+      hub.subscribe({
+        type: "client",
+        clientId,
+        interfaceId: "web",
+        capabilities: [],
+        ...(actorPrincipalId ? { actorPrincipalId } : {}),
+        callback: () => {
+          received[key]! += 1;
+        },
+      });
+    client("mac", "guardianMac", "principal-g");
+    client("web", "guardianWeb", "principal-g");
+    client("other", "otherUser", "principal-x");
+    client("legacy", "noPrincipal", undefined);
+    hub.subscribe({
+      type: "process",
+      callback: () => {
+        received.process! += 1;
+      },
+    });
+
+    await hub.publish(makeEvent(), { targetActorPrincipalId: "principal-g" });
+
+    expect(received).toEqual({
+      guardianMac: 1,
+      guardianWeb: 1,
+      otherUser: 0,
+      noPrincipal: 0,
+      process: 0,
+    });
+  });
+});

package/src/__tests__/assistant-stream-state.test.ts

@@ -491,6 +491,28 @@ describe("assistant-stream-state", () => {
       expect(procReplay).toEqual([]);
     });
 
+    test("principal-targeted events only replay to that principal's clients", () => {
+      stampAndBuffer(mkEvent(), {
+        targeting: { targetActorPrincipalId: "principal-g" },
+      });
+
+      const guardian = getReplayWindow(0, {
+        ...WEB_CLIENT,
+        actorPrincipalId: "principal-g",
+      });
+      const other = getReplayWindow(0, {
+        ...WEB_CLIENT,
+        actorPrincipalId: "principal-x",
+      });
+      const noPrincipal = getReplayWindow(0, WEB_CLIENT);
+      const proc = getReplayWindow(0, PROCESS_SUB);
+
+      expect(guardian!.map((e) => e.seq)).toEqual([1]);
+      expect(other).toEqual([]);
+      expect(noPrincipal).toEqual([]);
+      expect(proc).toEqual([]);
+    });
+
     test("mixed targeting across events filters per-entry", () => {
       /**
        * A ring with untargeted, capability-targeted, and excluded events

package/src/__tests__/emit-signal-routing-intent.test.ts

@@ -662,7 +662,7 @@ describe("high/critical urgency channel force", () => {
       sourceChannel: "watcher" | "assistant_tool",
     ) {
       return emitNotificationSignal({
-        sourceEventName: "watcher.escalation",
+        sourceEventName: "watcher.notification",
         sourceChannel,
         sourceContextId: "watch-1",
         routingIntent: "single_channel",

package/src/__tests__/events-tail-route.test.ts

@@ -170,6 +170,31 @@ describe("GET events/tail", () => {
     expect(other.events.map((e) => e.seq)).toEqual([1, 2]);
   });
 
+  test("returns a principal-targeted event only to that principal's client", () => {
+    stampAndBuffer(mkEvent()); // seq 1, untargeted
+    stampAndBuffer(mkEvent(), {
+      targeting: { targetActorPrincipalId: "principal-g" },
+    }); // seq 2
+
+    const client = {
+      "x-vellum-client-id": "c",
+      "x-vellum-interface-id": "web",
+    };
+    const guardian = callTail(
+      { conversationId: CONV, fromSeq: "0" },
+      { ...client, "x-vellum-actor-principal-id": "principal-g" },
+    );
+    const other = callTail(
+      { conversationId: CONV, fromSeq: "0" },
+      { ...client, "x-vellum-actor-principal-id": "principal-x" },
+    );
+    const anonymous = callTail({ conversationId: CONV, fromSeq: "0" });
+
+    expect(guardian.events.map((e) => e.seq)).toEqual([1, 2]);
+    expect(other.events.map((e) => e.seq)).toEqual([1]);
+    expect(anonymous.events.map((e) => e.seq)).toEqual([1]);
+  });
+
   test("toSeq bounds the window inclusively and moves the frontier", () => {
     // GIVEN five buffered events for the conversation (seq 1..5)
     for (let i = 0; i < 5; i++) {

package/src/__tests__/heartbeat-service.test.ts

@@ -334,11 +334,10 @@ const SCAFFOLD_PERSONA = stripCommentLines(GUARDIAN_PERSONA_TEMPLATE).trim();
 const { resolveCallSiteConfig } = await import("../config/llm-resolver.js");
 const { LLMSchema } = await import("../config/schemas/llm.js");
 
-// Capture broadcastMessage so tests can observe the alerts and
-// conversation-created events the heartbeat service emits directly.
+// Capture broadcastMessage so tests can observe the conversation-created
+// events the heartbeat service emits directly.
 type BroadcastedMessage = { type: string; [key: string]: unknown };
 const broadcastedMessages: BroadcastedMessage[] = [];
-let onBroadcast: ((msg: BroadcastedMessage) => void) | null = null;
 
 mock.module("../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
@@ -347,7 +346,6 @@ mock.module("../runtime/assistant-event-hub.js", () => ({
   },
   broadcastMessage: (msg: BroadcastedMessage) => {
     broadcastedMessages.push(msg);
-    onBroadcast?.(msg);
   },
 }));
 
@@ -357,7 +355,6 @@ describe("HeartbeatService", () => {
     content: string;
     options?: { callSite?: string };
   }>;
-  let alerterCalls: Array<{ type: string; title: string; body: string }>;
 
   afterEach(() => {
     // Clean up workspace files between tests so file-existence tests don't leak
@@ -368,13 +365,7 @@ describe("HeartbeatService", () => {
 
   beforeEach(() => {
     processMessageCalls = [];
-    alerterCalls = [];
     broadcastedMessages.length = 0;
-    onBroadcast = (msg) => {
-      if (msg.type === "heartbeat_alert") {
-        alerterCalls.push(msg as { type: string; title: string; body: string });
-      }
-    };
     createdConversations.length = 0;
     conversationIdCounter = 0;
     mockStoredMessages.length = 0;
@@ -693,21 +684,6 @@ describe("HeartbeatService", () => {
     expect(processMessageCalls).toHaveLength(1);
   });
 
-  test("alerts on processMessage failure", async () => {
-    const service = createService({
-      processMessage: async () => {
-        throw new Error("LLM timeout");
-      },
-    });
-
-    await service.runOnce();
-
-    expect(alerterCalls).toHaveLength(1);
-    expect(alerterCalls[0].type).toBe("heartbeat_alert");
-    expect(alerterCalls[0].title).toBe("Heartbeat Failed");
-    expect(alerterCalls[0].body).toBe("LLM timeout");
-  });
-
   test("successful run updates lastRunAt and nextRunAt", async () => {
     const service = createService();
     expect(service.lastRunAt).toBeNull();
@@ -724,24 +700,6 @@ describe("HeartbeatService", () => {
     );
   });
 
-  test("alerts on conversation creation failure", async () => {
-    // Override createConversation to throw via a fresh import trick:
-    // Since createConversation is mocked at module level, we simulate
-    // this by having processMessage throw before it's called — but the
-    // real fix is that executeRun wraps createConversation in the try/catch.
-    // We verify by checking that any error in executeRun triggers the alert.
-    const service = createService({
-      processMessage: async () => {
-        throw new Error("DB locked");
-      },
-    });
-
-    await service.runOnce();
-
-    expect(alerterCalls).toHaveLength(1);
-    expect(alerterCalls[0].body).toBe("DB locked");
-  });
-
   test("resetTimer() pushes nextRunAt forward", () => {
     const service = createService();
     service.start();
@@ -1467,21 +1425,6 @@ describe("HeartbeatService", () => {
       });
     });
 
-    test("CAS false suppresses failure alerter and feed event", async () => {
-      mockCompleteHeartbeatRun.mockImplementation(() => false);
-
-      const service = createService({
-        processMessage: async () => {
-          throw new Error("LLM timeout");
-        },
-      });
-
-      await service.runOnce();
-
-      // completeHeartbeatRun returned false, so alerter should NOT be called
-      expect(alerterCalls).toHaveLength(0);
-    });
-
     test("active-hours skip calls skipHeartbeatRun", async () => {
       setHeartbeatConfig({ activeHoursStart: 9, activeHoursEnd: 17 });
 

package/src/__tests__/notification-telegram-adapter.test.ts

@@ -183,7 +183,7 @@ describe("TelegramAdapter", () => {
 
     await adapter.send(
       makePayload({
-        sourceEventName: "watcher.escalation",
+        sourceEventName: "watcher.notification",
         copy: {
           title: " ",
           body: "",
@@ -191,7 +191,7 @@ describe("TelegramAdapter", () => {
       }),
       makeDestination(),
     );
-    expect(sendCalls[2]?.text).toBe("watcher escalation");
+    expect(sendCalls[2]?.text).toBe("watcher notification");
   });
 
   // ── Access request inline keyboard tests ──────────────────────────────

package/src/__tests__/notification-vellum-adapter.test.ts

@@ -35,6 +35,7 @@ import type {
   ChannelDeliveryPayload,
   ChannelDestination,
 } from "../notifications/types.js";
+import type { BroadcastMessageOptions } from "../runtime/assistant-event-hub.js";
 
 function makePayload(
   overrides?: Partial<ChannelDeliveryPayload>,
@@ -362,3 +363,36 @@ describe("VellumAdapter update", () => {
     expect(result.error).toBe("DB write failed");
   });
 });
+
+describe("VellumAdapter guardian scoping", () => {
+  function captureOptions(): {
+    adapter: VellumAdapter;
+    options: Array<BroadcastMessageOptions | undefined>;
+  } {
+    const options: Array<BroadcastMessageOptions | undefined> = [];
+    const adapter = new VellumAdapter((_msg, _conversationId, opts) => {
+      options.push(opts);
+    });
+    return { adapter, options };
+  }
+
+  test("a guardian-sensitive intent is delivered only to the guardian's connections", async () => {
+    const { adapter, options } = captureOptions();
+    await adapter.send(
+      makePayload({ sourceEventName: "guardian.question", urgency: "high" }),
+      makeDestination({ metadata: { guardianPrincipalId: "principal-g" } }),
+    );
+
+    expect(options).toEqual([{ targetActorPrincipalId: "principal-g" }]);
+  });
+
+  test("an ordinary intent is broadcast to every connection", async () => {
+    const { adapter, options } = captureOptions();
+    await adapter.send(
+      makePayload({ sourceEventName: "schedule.notify" }),
+      makeDestination({ metadata: { guardianPrincipalId: "principal-g" } }),
+    );
+
+    expect(options).toEqual([{ targetActorPrincipalId: undefined }]);
+  });
+});

package/src/api/events/notification-conversation-created.ts

@@ -4,8 +4,9 @@
  * Server → client broadcast emitted when an incoming notification
  * creates a new vellum conversation. Clients use it to place the
  * conversation in the sidebar (`groupId`, `source`) and decide whether
- * to raise a fallback OS banner (`silent`). `targetGuardianPrincipalId`
- * scopes guardian-sensitive conversations to a bound identity.
+ * to raise a fallback OS banner (`silent`). A guardian-sensitive
+ * conversation is announced only to connections authenticated as the
+ * guardian named in `targetGuardianPrincipalId`.
  *
  * Canonical wire-contract source. Daemon code imports the type
  * directly from this file; external consumers import via
@@ -21,8 +22,9 @@ export const NotificationConversationCreatedEventSchema = z.object({
   sourceEventName: z.string(),
   /**
    * When set, this conversation was created for a guardian-sensitive
-   * notification and should only be surfaced by clients bound to this
-   * guardian identity.
+   * notification. The daemon delivers the event only to connections whose
+   * verified principal is this guardian, so every client that receives it
+   * is one it was meant for.
    */
   targetGuardianPrincipalId: z.string().optional(),
   /**

package/src/api/events/notification-intent.ts

@@ -2,8 +2,10 @@
  * `notification_intent` SSE event.
  *
  * Broadcast when a notification should be displayed. Clients turn it
- * into a local OS / in-app notification, filter guardian-scoped intents
- * to matching devices, and ack delivery back to the daemon.
+ * into a local OS / in-app notification and ack delivery back to the
+ * daemon. A guardian-scoped intent (`targetGuardianPrincipalId` set) is
+ * delivered only to connections whose verified principal is that
+ * guardian, so every client that receives one is meant to show it.
  *
  * `silent` tells the client not to post the intent to the OS
  * notification surface (non-banner side effects still run); the server

package/src/api/index.ts

@@ -50,7 +50,6 @@ import { DocumentEditorUpdateEventSchema } from "./events/document-editor-update
 import { ErrorEventSchema } from "./events/error.js";
 import { GenerationCancelledEventSchema } from "./events/generation-cancelled.js";
 import { GenerationHandoffEventSchema } from "./events/generation-handoff.js";
-import { HeartbeatAlertEventSchema } from "./events/heartbeat-alert.js";
 import { HeartbeatConversationCreatedEventSchema } from "./events/heartbeat-conversation-created.js";
 import { HomeFeedUpdatedEventSchema } from "./events/home-feed-updated.js";
 import { HookEventSchema } from "./events/hook-event.js";
@@ -395,10 +394,6 @@ export {
   type GenerationHandoffEvent,
   GenerationHandoffEventSchema,
 } from "./events/generation-handoff.js";
-export {
-  type HeartbeatAlertEvent,
-  HeartbeatAlertEventSchema,
-} from "./events/heartbeat-alert.js";
 export {
   type HeartbeatConversationCreatedEvent,
   HeartbeatConversationCreatedEventSchema,
@@ -1039,7 +1034,6 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ErrorEventSchema,
   GenerationCancelledEventSchema,
   GenerationHandoffEventSchema,
-  HeartbeatAlertEventSchema,
   HeartbeatConversationCreatedEventSchema,
   HomeFeedUpdatedEventSchema,
   HookEventSchema,