@vellumai/assistant 0.12.2-dev.202609181913.1108ac3 → 0.12.2-dev.202609182015.188de8a

package/ARCHITECTURE.md

@@ -300,7 +300,7 @@ The WhatsApp channel enables inbound and outbound messaging via the Meta WhatsAp
 
 **Egress** (daemon WhatsApp transport, `src/messaging/providers/whatsapp/`):
 
-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 exception is on the gateway side: its replies to invite and verification codes it intercepts at ingress (`deliverVerificationReply` in `gateway/src/verification/reply-delivery.ts`) still POST to the callback URL, which no gateway route serves, so those replies are not delivered.
+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.

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.202609181913.1108ac3",
+  "version": "0.12.2-dev.202609182015.188de8a",
   "license": "MIT",
   "type": "module",
   "exports": {

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__/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/cli/commands/__tests__/notifications.test.ts

@@ -175,7 +175,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -186,7 +186,7 @@ describe("notifications send", () => {
 
     const body = lastSendBody();
     expect(body.sourceChannel).toBe("assistant_tool");
-    expect(body.sourceEventName).toBe("user.send_notification");
+    expect(body.sourceEventName).toBe("schedule.notify");
     const payload = body.contextPayload as Record<string, unknown>;
     expect(payload.requestedMessage).toBe("Hello");
   });
@@ -221,7 +221,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
       "--preferred-channels",
@@ -241,7 +241,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
       "--urgency",
@@ -265,7 +265,7 @@ describe("notifications send", () => {
       "--source-channel",
       "water_reminder",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -300,7 +300,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -320,7 +320,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
     ]);
@@ -335,7 +335,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -359,7 +359,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -384,7 +384,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);

package/src/ipc/assistant-server.ts

@@ -59,6 +59,7 @@ import { RouteResponse } from "../runtime/routes/types.js";
 import { getLogger } from "../util/logger.js";
 import { mapGatewayIpcConnectError } from "./gateway-ipc-errors.js";
 import { ACTIVATION_SYNC_IPC_METHODS } from "./routes/activation-sync-ipc-routes.js";
+import { CHANNEL_REPLY_IPC_METHODS } from "./routes/channel-reply-ipc-routes.js";
 import { CONTACTS_INFO_IPC_METHODS } from "./routes/contacts-info-ipc-routes.js";
 import { CONTACTS_MIRROR_IPC_METHODS } from "./routes/contacts-mirror-ipc-routes.js";
 import { CONVERSATION_SYNC_IPC_METHODS } from "./routes/conversation-sync-ipc-routes.js";
@@ -216,6 +217,7 @@ export class AssistantIpcServer {
     // never in ROUTES.
     for (const methodMap of [
       INVITE_IPC_METHODS,
+      CHANNEL_REPLY_IPC_METHODS,
       CONTACTS_INFO_IPC_METHODS,
       CONTACTS_MIRROR_IPC_METHODS,
       GUARDIAN_LABEL_IPC_METHODS,

package/src/ipc/routes/__tests__/channel-reply-ipc-routes.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The gateway's replies to messages it answered itself reach the person
+ * through the channel transport, the same one a turn's reply uses.
+ *
+ * The Bot API call is the boundary: everything between the gateway's request
+ * and Telegram's `sendMessage` is the real code, so the assertion is that the
+ * text a person would read left for their chat, in the topic they wrote from.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { DELIVER_GATEWAY_REPLY_IPC_METHOD } from "@vellumai/gateway-client";
+
+type CallTelegramBotApi =
+  typeof import("../../../messaging/providers/telegram-bot/api.js").callTelegramBotApi;
+
+const callTelegramBotApiMock = mock<CallTelegramBotApi>(
+  async () => ({ message_id: 42 }) as never,
+);
+
+// Spread the actual module so exports this suite does not touch stay
+// importable by files that share the bun process.
+const actualTelegramApi =
+  await import("../../../messaging/providers/telegram-bot/api.js");
+mock.module("../../../messaging/providers/telegram-bot/api.js", () => ({
+  ...actualTelegramApi,
+  callTelegramBotApi: (method: string, body: Record<string, unknown>) =>
+    callTelegramBotApiMock(method, body),
+}));
+
+const { CHANNEL_REPLY_IPC_METHODS } =
+  await import("../channel-reply-ipc-routes.js");
+const { BadGatewayError, BadRequestError } =
+  await import("../../../runtime/routes/errors.js");
+
+const deliverGatewayReply =
+  CHANNEL_REPLY_IPC_METHODS[DELIVER_GATEWAY_REPLY_IPC_METHOD]!;
+
+// The callback URL exactly as the gateway's Telegram webhook builds it for a
+// message sent in a topic.
+const TELEGRAM_CALLBACK = "http://127.0.0.1:7830/deliver/telegram?threadId=7";
+
+beforeEach(() => {
+  callTelegramBotApiMock.mockClear();
+});
+
+describe("deliver_gateway_reply", () => {
+  test("sends the reply to the person's Telegram chat, in their topic", async () => {
+    const result = await deliverGatewayReply({
+      body: {
+        callbackUrl: TELEGRAM_CALLBACK,
+        chatId: "12345",
+        text: "Welcome! You've been granted access.",
+        assistantId: "self",
+      },
+    });
+
+    const sends = callTelegramBotApiMock.mock.calls.filter(
+      ([method]) => method === "sendMessage",
+    );
+    expect(sends).toHaveLength(1);
+    expect(sends[0]![1]).toMatchObject({
+      chat_id: "12345",
+      text: "Welcome! You've been granted access.",
+      message_thread_id: 7,
+    });
+    expect(result).toEqual({ ok: true, messageIds: ["42"] });
+  });
+
+  test("answers a send the channel refuses with a status, not a bare error", async () => {
+    // Only a RouteError crosses IPC with a status; without one the gateway
+    // reads the refusal as a daemon that never answered.
+    callTelegramBotApiMock.mockImplementationOnce(async () => {
+      throw new Error("Bad Request: chat not found");
+    });
+
+    const rejection = expect(
+      deliverGatewayReply({
+        body: {
+          callbackUrl: TELEGRAM_CALLBACK,
+          chatId: "12345",
+          text: "Welcome! You've been granted access.",
+        },
+      }),
+    ).rejects;
+    await rejection.toBeInstanceOf(BadGatewayError);
+    await rejection.toMatchObject({ statusCode: 502 });
+  });
+
+  test("refuses a callback no channel transport owns, sending nothing", async () => {
+    await expect(
+      deliverGatewayReply({
+        body: {
+          callbackUrl: "http://127.0.0.1:7830/deliver/email",
+          chatId: "someone@example.com",
+          text: "Verification successful.",
+        },
+      }),
+    ).rejects.toBeInstanceOf(BadRequestError);
+    expect(callTelegramBotApiMock).not.toHaveBeenCalled();
+  });
+
+  test("refuses a request with no text, sending nothing", async () => {
+    await expect(
+      deliverGatewayReply({
+        body: { callbackUrl: TELEGRAM_CALLBACK, chatId: "12345", text: "" },
+      }),
+    ).rejects.toBeInstanceOf(BadRequestError);
+    expect(callTelegramBotApiMock).not.toHaveBeenCalled();
+  });
+});

package/src/ipc/routes/channel-reply-ipc-routes.ts

@@ -0,0 +1,73 @@
+/**
+ * IPC-only channel reply method called by the gateway over the assistant IPC
+ * socket (`ipcCallAssistant`).
+ *
+ * The gateway answers some inbound messages itself without forwarding them
+ * (a verification code, an invite redemption), so the assistant never sees
+ * them. Its reply still has to reach the person, and the channel transports
+ * that can send it live here. This hands the reply to the transport the
+ * inbound message's callback URL names, which is how the daemon's own
+ * intercepts answer an inbound message: the gateway sends through the same
+ * transports and never to a provider itself.
+ *
+ * Nothing is recorded in a conversation. The message the reply answers never
+ * entered one, so a row for the reply would stand alone in a transcript that
+ * does not hold what it responds to.
+ */
+
+import {
+  DELIVER_GATEWAY_REPLY_IPC_METHOD,
+  GatewayReplyRequestSchema,
+} from "@vellumai/gateway-client";
+
+import {
+  deliverDirect,
+  isDirectDelivery,
+} from "../../messaging/providers/index.js";
+import {
+  BadGatewayError,
+  BadRequestError,
+} from "../../runtime/routes/errors.js";
+import { parseBody } from "../../runtime/routes/parse-body.js";
+import type { RouteHandlerArgs } from "../../runtime/routes/types.js";
+
+/**
+ * Deliver a gateway-composed reply through the channel transport its callback
+ * URL names. Refuses a callback no transport owns rather than fetching it, so
+ * the gateway learns the channel cannot be answered this way.
+ *
+ * A send the channel refuses is answered as a `BadGatewayError`, as
+ * `channels/send` answers it: only a `RouteError` carries a status over IPC,
+ * and the gateway reads an error without one as a daemon that never answered.
+ */
+export async function handleDeliverGatewayReply({
+  body = {},
+}: RouteHandlerArgs) {
+  const { callbackUrl, chatId, text, assistantId } = parseBody(
+    GatewayReplyRequestSchema,
+    body,
+  );
+  if (!isDirectDelivery(callbackUrl)) {
+    throw new BadRequestError("No channel transport owns this callback URL");
+  }
+  try {
+    return await deliverDirect(callbackUrl, {
+      chatId,
+      text,
+      ...(assistantId ? { assistantId } : {}),
+    });
+  } catch (err) {
+    throw new BadGatewayError(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * IPC-only channel reply methods, keyed by IPC operationId. Registered
+ * directly on the assistant IPC server (see `assistant-server.ts`).
+ */
+export const CHANNEL_REPLY_IPC_METHODS: Record<
+  string,
+  (args: RouteHandlerArgs) => unknown
+> = {
+  [DELIVER_GATEWAY_REPLY_IPC_METHOD]: handleDeliverGatewayReply,
+};

package/src/messaging/providers/discord/send.ts

@@ -41,8 +41,9 @@ const DISCORD_ALLOWED_MENTIONS = { parse: ["users"] } as const;
 
 /**
  * Upper bound on an outbound attachment. Discord's real limit is the guild's
- * boost tier (10 MiB with no boosts, more above that), which the API does not
- * expose here, so the client-side guard is only the ceiling no tier exceeds:
+ * boost tier (20 MiB per file by default, more above that; see
+ * https://discord.com/developers/docs/reference#uploading-files), which the
+ * API does not expose here, so the client-side guard is only the ceiling no tier exceeds:
  * past it the upload is provably futile and not worth the bandwidth. Anything
  * under it is attempted and, if the guild's own tier rejects it, reported
  * through the same failure notice as any other attachment error.

package/src/messaging/providers/telegram-bot/send.test.ts

@@ -692,7 +692,9 @@ describe("telegramTransport.streamReply", () => {
 });
 
 describe("sendTelegramAttachments", () => {
-  // The Bot API's sendDocument upload cap; the sender skips anything larger.
+  // The Bot API's multipart upload limits: a photo, and any other file. The
+  // sender skips anything over the second.
+  const MAX_PHOTO_BYTES = 10 * 1024 * 1024;
   const MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024;
 
   function attachment(
@@ -759,6 +761,33 @@ describe("sendTelegramAttachments", () => {
     expect(await document.text()).toBe("pdf");
   });
 
+  test("sends an image over the photo limit with sendDocument", async () => {
+    storeHolds({
+      "att-1": Buffer.alloc(MAX_PHOTO_BYTES),
+      "att-2": Buffer.alloc(MAX_PHOTO_BYTES + 1),
+    });
+
+    const result = await sendTelegramAttachments("123", [
+      attachment("att-1", "fits.png", "image/png", MAX_PHOTO_BYTES),
+      attachment("att-2", "scan.png", "image/png", MAX_PHOTO_BYTES + 1),
+    ]);
+
+    expect(multipartCalls().map((c) => c.method)).toEqual([
+      "sendPhoto",
+      "sendDocument",
+    ]);
+    const document = multipartCalls()[1]?.form.get("document") as File;
+    expect(document.name).toBe("scan.png");
+    expect(document.type).toBe("image/png");
+    expect(document.size).toBe(MAX_PHOTO_BYTES + 1);
+    expect(noticeTexts()).toEqual([]);
+    expect(result).toEqual({
+      allFailed: false,
+      failureCount: 0,
+      totalCount: 2,
+    });
+  });
+
   test("targets the topic on both the upload and the failure notice", async () => {
     storeHolds({ "att-1": Buffer.from("png") });
 

package/src/messaging/providers/telegram-bot/send.ts

@@ -31,7 +31,9 @@ const TELEGRAM_MAX_MESSAGE_LEN = 4000;
 /** Telegram Bot API enforces a 1-64 byte limit on InlineKeyboardButton callback_data. */
 const TELEGRAM_MAX_CALLBACK_DATA_BYTES = 64;
 
-// Telegram Bot API sendDocument upload limit is 50 MB
+// Bot API limits for a multipart upload: 10 MB for a photo, 50 MB for any
+// other file (https://core.telegram.org/bots/api#sending-files).
+const TELEGRAM_MAX_PHOTO_BYTES = 10 * 1024 * 1024;
 const TELEGRAM_MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024;
 
 const TELEGRAM_IMAGE_MIME_PREFIXES = [
@@ -296,8 +298,9 @@ export type TelegramAttachmentResult = {
 };
 
 /**
- * Send attachments to a Telegram chat, using sendPhoto for images and
- * sendDocument for everything else.
+ * Send attachments to a Telegram chat, using sendPhoto for an image within
+ * the photo limit and sendDocument for everything else, so an image over it
+ * still arrives as a file.
  */
 export async function sendTelegramAttachments(
   chatId: string,
@@ -351,10 +354,10 @@ export async function sendTelegramAttachments(
         form.set("message_thread_id", String(threadFields.message_thread_id));
       }
 
-      const isImage = TELEGRAM_IMAGE_MIME_PREFIXES.some((p) =>
-        mimeType.startsWith(p),
-      );
-      if (isImage) {
+      const sendsAsPhoto =
+        TELEGRAM_IMAGE_MIME_PREFIXES.some((p) => mimeType.startsWith(p)) &&
+        content.length <= TELEGRAM_MAX_PHOTO_BYTES;
+      if (sendsAsPhoto) {
         form.set("photo", blob, filename);
         await callTelegramBotApiMultipart("sendPhoto", form);
       } else {

package/src/notifications/README.md

@@ -300,7 +300,9 @@ Local SSE via the assistant's broadcast mechanism. The `VellumAdapter` emits a `
 - `title` and `body` -- rendered notification copy
 - `deepLinkMetadata` -- optional metadata for navigating to the relevant context (e.g. `{ conversationId }`)
 
-The macOS client posts a native `UNUserNotificationCenter` notification from this payload. When the user taps the notification, the client uses `deepLinkMetadata` to navigate to the relevant conversation.
+Every first-party client runs the shared web renderer (browser, desktop app, mobile apps), which posts a local notification from this payload and acks the delivery. When the user taps the notification, the client uses `deepLinkMetadata` to navigate to the relevant conversation.
+
+A guardian-sensitive notification (approval requests, access requests, channel activation codes) carries `targetGuardianPrincipalId` and is published with `targetActorPrincipalId`, so the event hub delivers it only to connections authenticated as the guardian. The client shows it when the sending assistant is new enough to apply that targeting (`clients/web/src/lib/backwards-compat/guardian-notification-targeting.ts`) and drops it otherwise.
 
 ### Platform (always connected)
 

package/src/notifications/__tests__/broadcaster.test.ts

@@ -140,7 +140,7 @@ function makeSignal(
     createdAt: 1700000000000,
     sourceChannel: "scheduler",
     sourceContextId: "ctx-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {},
     attentionHints: {
       requiresAction: false,

package/src/notifications/__tests__/copy-composer.test.ts

@@ -21,7 +21,7 @@ function makeSignal(
     createdAt: Date.now(),
     sourceChannel: "scheduler",
     sourceContextId: "ctx-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {},
     attentionHints: {
       requiresAction: false,

package/src/notifications/__tests__/decision-engine.test.ts

@@ -99,7 +99,7 @@ function makeAssistantToolSignal(
     createdAt: Date.now(),
     sourceChannel: "assistant_tool",
     sourceContextId: "tool-call-1",
-    sourceEventName: "user.send_notification",
+    sourceEventName: "assistant.share",
     contextPayload: {
       requestedMessage: "exact verbatim text here",
       requestedTitle: "Custom Title",
@@ -905,7 +905,9 @@ describe("scheduler requested-message pass-through in notification decision engi
       expect(decision.reasoningSummary).not.toBe(
         "scheduler requested-message pass-through",
       );
-      expect(decision.reasoningSummary).not.toBe("schedule_result pass-through");
+      expect(decision.reasoningSummary).not.toBe(
+        "schedule_result pass-through",
+      );
     } finally {
       providerSendMessage = previousSendMessage;
     }

package/src/notifications/__tests__/deterministic-checks.test.ts

@@ -107,10 +107,10 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("fails when body is the raw source event name", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user.send_notification" },
+        vellum: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);
@@ -119,10 +119,10 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("fails when body matches the normalized source event name", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user send notification" },
+        vellum: { title: "Reminder", body: "assistant share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);
@@ -174,11 +174,11 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   test("still validates body quality for channels with rendered copy", async () => {
     // Even when some channels lack copy (broadcaster fallback territory),
     // channels that DO have copy must still pass the empty/event-name checks.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       selectedChannels: ["vellum", "telegram"],
       renderedCopy: {
-        telegram: { title: "Reminder", body: "user.send_notification" },
+        telegram: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, {
@@ -194,7 +194,7 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
     // a usable body (no template for sourceEventName → buildGenericCopy
     // returns body=""), the gate must fail-closed rather than letting
     // dispatchDecision report 0/N sent.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       selectedChannels: ["vellum"],
       renderedCopy: {},
@@ -218,7 +218,7 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("passes when shouldNotify is false regardless of copy contents", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       shouldNotify: false,
       // Empty body + event-name body would both fail the copy check if
@@ -286,11 +286,11 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   test("still fails non-pass-through decision when body matches event name", async () => {
     // Regression guard: the pass-through short-circuit must not weaken
     // the check for LLM/fallback paths.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       reasoningSummary: "llm classification",
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user.send_notification" },
+        vellum: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);

package/src/notifications/__tests__/home-feed-side-effect.test.ts

@@ -281,7 +281,9 @@ describe("writeHomeFeedItemForSignal", () => {
       "The deployment completed successfully.",
     );
     expect(appendCalls[0]!.conversationId).toBe("conv-source-1");
-    expect(appendCalls[0]!.metadata?.notificationConversationMessageId).toBeUndefined();
+    expect(
+      appendCalls[0]!.metadata?.notificationConversationMessageId,
+    ).toBeUndefined();
     expect(messageAppends).toEqual([]);
     expect(messagesInvalidated).toEqual([]);
     expect(conversationLookups).toEqual(["conv-source-1", "conv-source-1"]);
@@ -956,7 +958,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
@@ -970,7 +972,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
@@ -1126,7 +1128,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 

package/src/notifications/copy-composer.ts

@@ -331,19 +331,6 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.body, "A watcher event occurred"),
   }),
 
-  "watcher.escalation": (payload) => ({
-    title: str(payload.title, "Watcher Escalation"),
-    body: str(payload.body, "A watcher event requires your attention"),
-  }),
-
-  "tool_confirmation.required_action": (payload) => {
-    const toolName = str(payload.toolName, "A tool");
-    return {
-      title: `${toolName} needs your confirmation`,
-      body: `${toolName} requires your confirmation`,
-    };
-  },
-
   // Titled by what was done rather than by the kind of event: the summary's
   // first sentence is the outcome ("Finished the fuel-system diagnostic app"),
   // which is what a reader scanning the bell wants to see. A producer that
@@ -385,16 +372,6 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
       body: summary !== "" ? summary : describeUnclassifiedFailure(payload),
     };
   },
-
-  "quick_chat.response_ready": (payload) => ({
-    title: "Quick chat reply ready",
-    body: str(payload.preview, "Your quick chat response is ready"),
-  }),
-
-  "voice.response_ready": (payload) => ({
-    title: "Voice reply ready",
-    body: str(payload.preview, "A voice response is ready"),
-  }),
 };
 
 /**

package/src/notifications/deterministic-checks.ts

@@ -254,7 +254,7 @@ function checkDedupe(
 /**
  * Fail-closed check that the rendered copy is real text and not an
  * accidental fallback leak (empty body, or body that is just the raw
- * source event name like "user.send_notification").
+ * source event name like "assistant.share").
  *
  * Only validates channels that the decision engine actually emitted
  * copy for. Channels appended after the decision (urgency-forced

package/src/notifications/home-feed-side-effect.ts

@@ -459,12 +459,10 @@ const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
 
 /**
  * Map a signal's source event to a feed category, or nothing when the event
- * has no entry. An unmapped event used to land in `system`, a bucket named
- * for our architecture rather than the user's world, and every deliberate
- * assistant notification (`user.send_notification`) ended up there. The
- * category is optional on the wire, so an event without a home simply
- * carries none: readers that filter by category skip it, and nothing has
- * to guess.
+ * has no entry. An unmapped event, such as a deliberate assistant
+ * notification (`assistant.share`), carries no category rather than a
+ * catch-all bucket named for our architecture: readers that filter by
+ * category skip it, and nothing has to guess.
  */
 function deriveCategory(
   signal: NotificationSignal,

package/src/notifications/signal.ts

@@ -59,8 +59,9 @@ export function isNotificationSourceChannel(
 
 export const NOTIFICATION_SOURCE_EVENT_NAMES = [
   {
-    id: "user.send_notification",
-    description: "User-initiated notification via assistant tool",
+    id: "assistant.share",
+    description:
+      "Assistant chose to tell the user something (`assistant notifications send`)",
   },
   {
     id: "schedule.notify",
@@ -113,28 +114,12 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     id: "watcher.notification",
     description: "Watcher detected a notable event",
   },
-  {
-    id: "watcher.escalation",
-    description: "Watcher event requiring immediate attention",
-  },
-  {
-    id: "tool_confirmation.required_action",
-    description: "Tool requires user confirmation before executing",
-  },
   { id: "activity.complete", description: "Background activity finished" },
   {
     id: "activity.failed",
     description:
       "Background job execution failed (model_provider, exception, or timeout)",
   },
-  {
-    id: "quick_chat.response_ready",
-    description: "Quick chat response ready for review",
-  },
-  {
-    id: "voice.response_ready",
-    description: "Voice response ready for playback",
-  },
   {
     id: "credential.health_alert",
     description:

package/src/runtime/AGENTS.md

@@ -277,6 +277,8 @@ Verification SESSION state (sessions, secrets, rate limits, validate+consume) AN
 
 The daemon relays session lifecycle operations over the `verification_sessions_*` IPC routes via `assistant/src/channels/gateway-verification-sessions.ts` and keeps what is presentation: message composition and channel delivery (`channel-verification-routes.ts`, `verification-outbound-actions.ts`). `channel-verification-service.ts` retains only guardian-delivery reads (`getGuardianBinding`, `isGuardian`, `isGuardianBoundForChannel`).
 
+The gateway answers a code (or an invite) it consumed at ingress with a reply it composes itself, and delivers it through the daemon's IPC-only `deliver_gateway_reply` method (`ipc/routes/channel-reply-ipc-routes.ts`), which hands it to the channel transport the inbound message's callback URL names. The gateway never sends to a provider itself: the transports are the one outbound path per channel, whoever composed the text. The reply is not recorded in a conversation, since the message it answers never entered one.
+
 The verified outcome is written in-process by the gateway: the HTTP guardian-attest handler calls `ContactStore.markChannelVerified` directly (verifiedVia "manual"); the code-match paths (text and the `verification_sessions_validate_consume` engine route) apply role side effects in-engine — guardian phone binding commits in the same gateway transaction as the consume. The revoke/downgrade outcome is relayed from the daemon via `ipcCallPersistent("mark_channel_revoked", …)` to `ContactStore.markChannelRevoked`.
 
 ## Rate Limiting & Diagnostics