@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/messaging/providers/slack/send.test.ts

@@ -28,7 +28,7 @@ mock.module("./api.js", () => ({
 // the (unmocked) shared transport, so thrown test errors must be real
 // instances or every branch under test would silently take the generic path.
 const { SlackApiError } = await import("./web-api-transport.js");
-const { sendSlackAssistantThreadStatus, sendSlackReply } =
+const { sendSlackAssistantThreadStatus, sendSlackReply, updateSlackMessage } =
   await import("./send.js");
 
 describe("sendSlackAssistantThreadStatus", () => {
@@ -80,9 +80,8 @@ describe("sendSlackAssistantThreadStatus", () => {
   });
 });
 
-describe("sendSlackReply update path", () => {
+describe("updateSlackMessage", () => {
   const messageTs = "1700000000.000100";
-  const threadTs = "1700000000.000001";
   const blocks: KnownBlock[] = [
     { type: "section", text: { type: "mrkdwn", text: "Final reply" } },
   ];
@@ -104,9 +103,7 @@ describe("sendSlackReply update path", () => {
       })
       .mockImplementationOnce(async () => ({ ok: true, ts: messageTs }));
 
-    const result = await sendSlackReply("C123", "Final reply", {
-      messageTs,
-      threadTs,
+    const result = await updateSlackMessage("C123", messageTs, "Final reply", {
       blocks,
     });
 
@@ -138,7 +135,7 @@ describe("sendSlackReply update path", () => {
       });
 
     await expect(
-      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+      updateSlackMessage("C123", messageTs, "Final reply", { blocks }),
     ).rejects.toThrow();
 
     // Two in-place chat.update attempts (with then without blocks), then give
@@ -155,7 +152,7 @@ describe("sendSlackReply update path", () => {
     });
 
     await expect(
-      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+      updateSlackMessage("C123", messageTs, "Final reply", { blocks }),
     ).rejects.toThrow();
 
     // A single failed chat.update, no chat.postMessage fallback: a transient
@@ -175,7 +172,7 @@ describe("sendSlackReply update path", () => {
     });
 
     await expect(
-      sendSlackReply("C123", "Final reply", { messageTs, threadTs, blocks }),
+      updateSlackMessage("C123", messageTs, "Final reply", { blocks }),
     ).rejects.toThrow();
 
     expect(callSlackApiMock).toHaveBeenCalledTimes(1);

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

@@ -9,6 +9,7 @@
 import type { Button, KnownBlock } from "@slack/types";
 import type {
   ApprovalUIMetadata,
+  MessageAudience,
   SlackStreamOp,
 } from "@vellumai/gateway-client";
 
@@ -133,9 +134,8 @@ export interface SlackSendOptions {
   blocks?: KnownBlock[];
   approval?: ApprovalUIMetadata;
   useBlocks?: boolean;
-  ephemeral?: boolean;
-  user?: string;
-  messageTs?: string;
+  /** Absent means the whole room sees it. */
+  audience?: MessageAudience;
 }
 
 export interface SlackSendResult {
@@ -210,15 +210,40 @@ function buildApprovalFallbackText(
 }
 
 /**
- * Send a Slack text message with optional Block Kit formatting.
+ * Post a Slack text message with optional Block Kit formatting.
  *
- * When `messageTs` is set this is strictly an in-place edit (`chat.update`),
- * mirroring `editMessage()` in ./withdraw.ts: a failed edit throws and is
- * never converted into a fresh `chat.postMessage`. Posting on failure would
- * leave the original message beside a duplicate ("ghost") reply; re-delivery
- * after a transient failure is the delivery layer's responsibility, not this
- * function's.
+ * Always posts. Replacing an existing message is {@link updateSlackMessage}.
  */
+/**
+ * Replace a Slack message in place via `chat.update`.
+ *
+ * A failed update throws rather than posting a fresh message, mirroring
+ * `editMessage()` in ./withdraw.ts: posting on failure leaves the original
+ * beside a duplicate reply. Re-delivery after a transient failure belongs to
+ * the delivery layer, not here.
+ */
+export async function updateSlackMessage(
+  chatId: string,
+  messageId: string,
+  text: string,
+  options?: { blocks?: readonly KnownBlock[]; useBlocks?: boolean },
+): Promise<SlackSendResult> {
+  const blocks = resolveBlocks(
+    text,
+    options?.blocks as KnownBlock[] | undefined,
+    undefined,
+    options?.useBlocks,
+  );
+  const result = await sendWithBlockFallback(
+    "chat.update",
+    { channel: chatId, text, ts: messageId },
+    blocks,
+    { fallbackWithoutBlocks: true },
+  );
+  log.info({ chatId, messageId }, "Slack message updated");
+  return result;
+}
+
 export async function sendSlackReply(
   chatId: string,
   text: string,
@@ -231,18 +256,6 @@ export async function sendSlackReply(
     options?.useBlocks,
   );
 
-  const messageTs = options?.messageTs;
-  if (typeof messageTs === "string" && messageTs.length > 0) {
-    const result = await sendWithBlockFallback(
-      "chat.update",
-      { channel: chatId, text, ts: messageTs },
-      blocks,
-      { fallbackWithoutBlocks: true },
-    );
-    log.info({ chatId, messageTs }, "Slack message updated");
-    return result;
-  }
-
   const postBase: Record<string, unknown> = { channel: chatId, text };
   if (options?.threadTs) {
     postBase.thread_ts = options.threadTs;
@@ -261,13 +274,12 @@ export async function sendSlackReply(
     fallbackText: approvalFallbackText,
   };
 
-  if (options?.ephemeral) {
-    if (!options.user) {
-      throw new Error("user is required for ephemeral messages");
-    }
+  // No guard for a missing reader: the audience carries the id with it, so
+  // "restricted to one reader, but which one" cannot be expressed.
+  if (options?.audience) {
     return sendWithBlockFallback(
       "chat.postEphemeral",
-      { ...postBase, user: options.user },
+      { ...postBase, user: options.audience.userId },
       blocks,
       fallbackOptions,
     );
@@ -372,7 +384,7 @@ export async function sendSlackAssistantThreadStatus(
   channel: string,
   threadTs: string,
   status: string,
-  loadingMessages?: string[],
+  loadingMessages?: readonly string[],
 ): Promise<void> {
   try {
     const body: Record<string, unknown> = {

package/src/messaging/providers/slack/transport.ts

@@ -8,6 +8,7 @@ import {
   sendSlackReaction,
   sendSlackReply,
   sendSlackStreamOp,
+  updateSlackMessage,
 } from "./send.js";
 
 const log = getLogger("slack-transport");
@@ -16,19 +17,16 @@ export const slackTransport: ChannelTransport = {
   channel: "slack",
 
   async deliver(ctx, payload) {
-    const { chatId, text, attachments, blocks } = payload;
+    const { chatId, text, attachments } = payload;
     const threadTs = ctx.params.threadTs;
 
     let sentTs: string | undefined;
     if (text) {
       const result = await sendSlackReply(chatId, text, {
         threadTs,
-        blocks,
         approval: payload.approval,
         useBlocks: payload.useBlocks,
-        ephemeral: payload.ephemeral,
-        user: payload.user,
-        messageTs: payload.messageTs,
+        audience: payload.audience,
       });
       sentTs = result.ts;
     } else if (payload.approval) {
@@ -54,27 +52,29 @@ export const slackTransport: ChannelTransport = {
     return { ok: true, ts: sentTs };
   },
 
-  async sendReaction(_ctx, payload) {
-    const reaction = payload.reaction;
-    if (!reaction) {
-      return { ok: true };
-    }
+  async edit(_ctx, target) {
+    const result = await updateSlackMessage(
+      target.chatId,
+      target.messageId,
+      target.text,
+      { blocks: target.blocks, useBlocks: target.useBlocks },
+    );
+    return { ok: true, ts: result.ts };
+  },
+
+  async react(_ctx, target) {
     await sendSlackReaction(
-      payload.chatId,
-      reaction.name,
-      reaction.messageTs,
-      reaction.action,
+      target.chatId,
+      target.emoji,
+      target.messageId,
+      target.action,
     );
     return { ok: true };
   },
 
-  async setThreadStatus(_ctx, payload) {
-    const status = payload.assistantThreadStatus;
-    if (!status) {
-      return { ok: true };
-    }
+  async setThreadStatus(_ctx, status) {
     await sendSlackAssistantThreadStatus(
-      status.channel,
+      status.chatId,
       status.threadTs,
       status.status,
       status.loadingMessages,
@@ -82,11 +82,7 @@ export const slackTransport: ChannelTransport = {
     return { ok: true };
   },
 
-  async streamReply(_ctx, payload) {
-    const op = payload.slackStream;
-    if (!op) {
-      return { ok: true };
-    }
-    return sendSlackStreamOp(payload.chatId, op);
+  async streamReply(_ctx, chatId, op) {
+    return sendSlackStreamOp(chatId, op);
   },
 };

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

@@ -272,10 +272,7 @@ describe("telegramTransport topic targeting", () => {
   });
 
   test("typing indicators target the topic", async () => {
-    await telegramTransport.sendTyping!(
-      topicCtx,
-      payload({ chatAction: "typing" }),
-    );
+    await telegramTransport.typing!(topicCtx, "123");
 
     expect(callTelegramBotApiMock).toHaveBeenCalledWith("sendChatAction", {
       chat_id: "123",
@@ -291,10 +288,7 @@ describe("telegramTransport topic targeting", () => {
     };
 
     await telegramTransport.deliver(bareCtx, payload({ useBlocks: false }));
-    await telegramTransport.sendTyping!(
-      bareCtx,
-      payload({ chatAction: "typing" }),
-    );
+    await telegramTransport.typing!(bareCtx, "123");
 
     expect(callTelegramBotApiMock).toHaveBeenCalledWith("sendMessage", {
       chat_id: "123",

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

@@ -67,12 +67,9 @@ export const telegramTransport: ChannelTransport = {
     return { ok: true };
   },
 
-  async sendTyping(ctx, payload) {
-    await sendTelegramTypingIndicator(payload.chatId, threadOptions(ctx));
-    log.debug(
-      { chatId: payload.chatId },
-      "Telegram typing indicator delivered (direct)",
-    );
+  async typing(ctx, chatId) {
+    await sendTelegramTypingIndicator(chatId, threadOptions(ctx));
+    log.debug({ chatId }, "Telegram typing indicator delivered (direct)");
     return { ok: true };
   },
 };

package/src/messaging/read-provider-metadata.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  groupingMessageId,
+  type ProviderMessageMetadata,
+} from "./provider-message-metadata.js";
+import type { SlackMessageMetadata } from "./providers/slack/message-metadata.js";
+import { readProviderMetadata } from "./read-provider-metadata.js";
+
+const CHANNEL = "C0123CHANNEL";
+const MESSAGE_TS = "1700000000.000100";
+const TARGET_TS = "1699999999.000001";
+
+function slackRow(
+  overrides: Partial<SlackMessageMetadata> = {},
+): SlackMessageMetadata {
+  return {
+    source: "slack",
+    channelId: CHANNEL,
+    channelTs: MESSAGE_TS,
+    eventKind: "message",
+    ...overrides,
+  };
+}
+
+describe("readProviderMetadata", () => {
+  it("reads a row that only has the legacy Slack envelope", () => {
+    // Slack's own envelope is mapped on read, so no row is rewritten.
+    const metadata = JSON.stringify({
+      slackMeta: JSON.stringify(slackRow({ threadTs: TARGET_TS })),
+    });
+
+    expect(readProviderMetadata(metadata)).toEqual({
+      source: "slack",
+      conversationExternalId: CHANNEL,
+      messageId: MESSAGE_TS,
+      threadId: TARGET_TS,
+      eventKind: "message",
+    } satisfies ProviderMessageMetadata);
+  });
+
+  it("carries the actor's provider id, not just a display name", () => {
+    // Trust is keyed on the actor everywhere else, and a channel describing
+    // who reacted needs an identity rather than a label.
+    const metadata = JSON.stringify({
+      slackMeta: JSON.stringify(
+        slackRow({ actorExternalUserId: "U0123", displayName: "Jason" }),
+      ),
+    });
+
+    const meta = readProviderMetadata(metadata);
+    expect(meta?.actorExternalId).toBe("U0123");
+    expect(meta?.displayName).toBe("Jason");
+  });
+
+  it("maps a reaction's target onto the neutral name", () => {
+    const metadata = JSON.stringify({
+      slackMeta: JSON.stringify(
+        slackRow({
+          eventKind: "reaction",
+          reaction: {
+            emoji: "thumbsup",
+            targetChannelTs: TARGET_TS,
+            op: "added",
+            actorDisplayName: "Jason",
+          },
+        }),
+      ),
+    });
+
+    const meta = readProviderMetadata(metadata);
+    expect(meta?.eventKind).toBe("reaction");
+    // No channel gives a reaction an id of its own, so the row must not claim
+    // its target's: two rows sharing one id break resolution by message id.
+    expect(meta?.messageId).toBeUndefined();
+    expect(meta?.reaction).toEqual({
+      targetMessageId: TARGET_TS,
+      emoji: "thumbsup",
+      op: "added",
+      actorDisplayName: "Jason",
+    });
+  });
+
+  it("leaves threadId absent when the row is not in a thread", () => {
+    // A thread id here asserts that a thread exists. Synthesizing one from
+    // the message's own id is what keyed conversations on threads that never
+    // did (LUM-3330, LUM-3340), so absence has to survive the mapping.
+    const metadata = JSON.stringify({
+      slackMeta: JSON.stringify(slackRow()),
+    });
+
+    const meta = readProviderMetadata(metadata);
+    expect(meta).not.toBeNull();
+    expect(meta?.threadId).toBeUndefined();
+    expect(meta?.messageId).toBe(MESSAGE_TS);
+  });
+
+  it("reads a channel this repo has no code for", () => {
+    // The point of the neutral shape. A plugin channel cannot add an adapter
+    // here, so it describes its own rows directly and every channel-agnostic
+    // reader understands them with no Vellum code naming that channel.
+    const metadata = JSON.stringify({
+      providerMeta: JSON.stringify({
+        source: "plugin",
+        conversationExternalId: "room-42",
+        messageId: "evt-9",
+        threadId: "evt-1",
+        eventKind: "reaction",
+        reaction: {
+          targetMessageId: "evt-1",
+          emoji: "tada",
+          op: "added",
+        },
+      } satisfies ProviderMessageMetadata),
+    });
+
+    const meta = readProviderMetadata(metadata);
+    expect(meta?.source).toBe("plugin");
+    expect(meta?.reaction?.targetMessageId).toBe("evt-1");
+    // Grouping is what history assembly keys on, so a reaction from an
+    // unknown channel lands beside the message it was attached to.
+    expect(groupingMessageId(meta!)).toBe("evt-1");
+  });
+
+  it("groups a message by its own id", () => {
+    const metadata = JSON.stringify({
+      slackMeta: JSON.stringify(slackRow()),
+    });
+
+    expect(groupingMessageId(readProviderMetadata(metadata)!)).toBe(MESSAGE_TS);
+  });
+
+  it("keeps provider fields the neutral schema does not name", () => {
+    // The schema passes through, so a channel can carry its own fields on the
+    // same object instead of getting a second envelope.
+    const metadata = JSON.stringify({
+      providerMeta: JSON.stringify({
+        source: "slack",
+        conversationExternalId: CHANNEL,
+        messageId: MESSAGE_TS,
+        eventKind: "message",
+        slackFiles: [{ name: "diagram.png" }],
+      }),
+    });
+
+    expect(
+      (readProviderMetadata(metadata) as Record<string, unknown> | null)
+        ?.slackFiles,
+    ).toEqual([{ name: "diagram.png" }]);
+  });
+
+  it("reads as null when the row carries neither envelope", () => {
+    expect(readProviderMetadata(JSON.stringify({ other: 1 }))).toBeNull();
+    expect(readProviderMetadata("not json")).toBeNull();
+    expect(readProviderMetadata(null)).toBeNull();
+  });
+});

package/src/messaging/read-provider-metadata.ts

@@ -0,0 +1,51 @@
+import { safeParseRecord } from "../util/json.js";
+import {
+  type ProviderMessageMetadata,
+  readProviderMessageMetadata,
+} from "./provider-message-metadata.js";
+import {
+  readSlackMetadataFromMessageMetadata,
+  slackMetadataAsProviderMetadata,
+} from "./providers/slack/message-metadata.js";
+
+/**
+ * Read a stored row's channel metadata in terms no single provider owns.
+ *
+ * Two ways a row can carry it, in this order.
+ *
+ * `providerMeta` is the neutral shape written directly. This is the path that
+ * matters most: a channel we have no code for, a plugin channel above all,
+ * can describe its own rows in it and every channel-agnostic reader
+ * understands them. History assembly, the conversation route and the
+ * transcript renderer then work for a channel nobody here has heard of.
+ *
+ * `slackMeta` is Slack's own envelope, mapped on read. It holds fields no
+ * other channel has an equivalent for, so Slack keeps writing it and loses
+ * nothing. A channel that writes `providerMeta` needs no adapter at all.
+ *
+ * Normalizing on read is what allows both. Writing stays where provider
+ * detail legitimately lives, and nothing is stored twice.
+ *
+ * A row with no recognized envelope, or one that fails validation, reads as
+ * null: callers already treat absent metadata as "not a channel row".
+ */
+export function readProviderMetadata(
+  metadata: string | null | undefined,
+  opts?: { allowFlatLegacy?: boolean },
+): ProviderMessageMetadata | null {
+  if (!metadata) {
+    return null;
+  }
+
+  // Malformed neutral metadata falls through to the provider envelopes rather
+  // than failing the read outright.
+  const neutral = readProviderMessageMetadata(
+    safeParseRecord(metadata).providerMeta,
+  );
+  if (neutral) {
+    return neutral;
+  }
+
+  const slackMeta = readSlackMetadataFromMessageMetadata(metadata, opts);
+  return slackMeta ? slackMetadataAsProviderMetadata(slackMeta) : null;
+}

package/src/notifications/__tests__/assistant-reply-producer.test.ts

@@ -94,6 +94,23 @@ mock.module("../../runtime/desktop-presence.js", () => ({
   },
 }));
 
+// Defaults to unfocused, so every other case in this file exercises the
+// unsuppressed path.
+let webFocused = false;
+let webPresenceShouldThrow = false;
+const webPresenceArgs: unknown[][] = [];
+const realWebPresence = await import("../../runtime/web-presence.js");
+mock.module("../../runtime/web-presence.js", () => ({
+  ...realWebPresence,
+  isWebConversationFocused: (...args: unknown[]) => {
+    webPresenceArgs.push(args);
+    if (webPresenceShouldThrow) {
+      throw new Error("simulated presence read failure");
+    }
+    return webFocused;
+  },
+}));
+
 const realAttentionStore =
   await import("../../persistence/conversation-attention-store.js");
 mock.module("../../persistence/conversation-attention-store.js", () => ({
@@ -183,6 +200,22 @@ function makeMacOriginatedMessage(): MessageRow {
   });
 }
 
+/**
+ * A turn opened from a plain browser tab, as opposed to the Electron desktop
+ * renderer sharing the same web bundle: `client.os` is `"web"` only when
+ * `detectClientOs()` fails to resolve an Electron host OS first.
+ */
+function makeWebOriginatedMessage(): MessageRow {
+  return makeMessage({
+    metadata: JSON.stringify({
+      userMessageChannel: "vellum",
+      userMessageInterface: "web",
+      client: { os: "web" },
+      clientOsFromRequest: true,
+    }),
+  });
+}
+
 function makeAssistantRow(content: ContentBlock[]): MessageRow {
   return makeMessage({
     id: ASSISTANT_MESSAGE_ID,
@@ -250,9 +283,12 @@ beforeEach(() => {
   messageLookups.length = 0;
   attachmentLookups.length = 0;
   desktopPresenceArgs.length = 0;
+  webPresenceArgs.length = 0;
   assistantAttachments = [];
   desktopAttended = false;
   desktopPresenceShouldThrow = false;
+  webFocused = false;
+  webPresenceShouldThrow = false;
   getConversationShouldThrow = false;
   conversationRow = makeConversation();
   assistantRow = makeAssistantRow([
@@ -433,6 +469,64 @@ describe("emitAssistantReplyNotification", () => {
     });
   });
 
+  // Same pre-gate as "desktop presence" above, scoped to a browser tab
+  // instead of the whole app.
+  describe("web presence", () => {
+    beforeEach(() => {
+      initiatingRow = makeWebOriginatedMessage();
+      webFocused = true;
+    });
+
+    test("marks the signal source-active while a web tab reports itself focused on this conversation", async () => {
+      await run();
+
+      expect(emitCalls).toHaveLength(1);
+      expect(emitCalls[0].attentionHints.visibleInSourceNow).toBe(true);
+      // Scoped to this conversation, unlike desktop attendance: a focused tab
+      // only speaks for the conversation it is actually looking at.
+      expect(webPresenceArgs).toEqual([[CONVERSATION_ID]]);
+    });
+
+    test("leaves the signal live when no web tab is focused on this conversation", async () => {
+      webFocused = false;
+
+      await run();
+
+      expect(emitCalls).toHaveLength(1);
+      expect(emitCalls[0].attentionHints.visibleInSourceNow).toBe(false);
+    });
+
+    test("leaves the signal live when the web presence flag is off", async () => {
+      setOverridesForTesting({ "web-presence-suppression": false });
+
+      await run();
+
+      expect(emitCalls).toHaveLength(1);
+      expect(emitCalls[0].attentionHints.visibleInSourceNow).toBe(false);
+      expect(webPresenceArgs).toEqual([]);
+    });
+
+    test("leaves the signal live when the web presence read throws", async () => {
+      webPresenceShouldThrow = true;
+
+      await run();
+
+      expect(emitCalls).toHaveLength(1);
+      expect(emitCalls[0].attentionHints.visibleInSourceNow).toBe(false);
+      expect(warnCalls).toHaveLength(1);
+    });
+
+    test("marks the signal source-active for a turn opened from the macOS app when a web tab is focused here", async () => {
+      initiatingRow = makeMacOriginatedMessage();
+
+      await run();
+
+      expect(emitCalls).toHaveLength(1);
+      expect(emitCalls[0].attentionHints.visibleInSourceNow).toBe(true);
+      expect(webPresenceArgs).toEqual([[CONVERSATION_ID]]);
+    });
+  });
+
   test("omits requestedTitle when the conversation has no title", async () => {
     conversationRow = makeConversation({ title: "   " });