@vellumai/assistant 0.11.4 → 0.11.5-dev.202608220019.a778cf0

package/src/messaging/providers/__tests__/transport-dispatch.test.ts

@@ -9,17 +9,19 @@ const slack = {
     Promise.resolve({ ts: "slack-ts" }),
   ),
   sendSlackReaction: mock((..._args: unknown[]) => Promise.resolve()),
-  sendSlackAssistantThreadStatus: mock((..._args: unknown[]) =>
-    Promise.resolve(),
-  ),
+  sendSlackAgentSessionStatus: mock((..._args: unknown[]) => Promise.resolve()),
   sendSlackAttachments: mock((..._args: unknown[]) =>
     Promise.resolve({ allFailed: false, failureCount: 0 }),
   ),
   sendSlackStreamOp: mock((..._args: unknown[]) =>
     Promise.resolve({ ok: true, ts: "stream-ts" }),
   ),
+  updateSlackMessage: mock((..._args: unknown[]) =>
+    Promise.resolve({ ts: "slack-ts" }),
+  ),
 };
 const telegram = {
+  editTelegramMessage: mock((..._args: unknown[]) => Promise.resolve()),
   sendTelegramReply: mock((..._args: unknown[]) => Promise.resolve()),
   sendTelegramRichReply: mock((..._args: unknown[]) => Promise.resolve()),
   sendTelegramTypingIndicator: mock((..._args: unknown[]) => Promise.resolve()),
@@ -57,8 +59,15 @@ mock.module("../../../util/logger.js", () => ({
   getLogger: () => ({ debug() {}, info() {}, warn() {}, error() {} }),
 }));
 
-const { deliverDirect, isDirectDelivery, getTransportForCallback } =
-  await import("../index.js");
+const {
+  deliverDirect,
+  editChannelMessage,
+  sendChannelStreamOp,
+  setChannelActivity,
+  supportsChannelActivity,
+  isDirectDelivery,
+  getTransportForCallback,
+} = await import("../index.js");
 
 const BASE = "https://gateway.internal";
 
@@ -134,56 +143,49 @@ describe("Slack sub-operation selection", () => {
     expect(opts.threadTs).toBe("1700.9");
   });
 
-  test("reaction routes to sendSlackReaction, not the text path", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/slack`,
-      payload({
-        reaction: {
-          action: "add",
-          name: "white_check_mark",
-          messageTs: "1700.5",
-        },
-      }),
-    );
-    expect(slack.sendSlackReaction).toHaveBeenCalledTimes(1);
+  test("editChannelMessage updates in place instead of posting", async () => {
+    await editChannelMessage(`${BASE}/deliver/slack`, {
+      chatId: "C1",
+      messageId: "1700.5",
+      text: "revised",
+    });
+
+    expect(slack.updateSlackMessage).toHaveBeenCalledTimes(1);
+    // The distinction the split exists for: an edit never reaches the post
+    // path, so a failed edit cannot become a second visible message.
     expect(slack.sendSlackReply).not.toHaveBeenCalled();
   });
 
-  test("assistantThreadStatus routes to sendSlackAssistantThreadStatus", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/slack`,
-      payload({
-        assistantThreadStatus: {
-          channel: "C1",
-          threadTs: "1700.5",
-          status: "is thinking",
-        },
-      }),
-    );
-    expect(slack.sendSlackAssistantThreadStatus).toHaveBeenCalledTimes(1);
+  test("setChannelActivity reaches Slack without touching the text path", async () => {
+    await setChannelActivity(`${BASE}/deliver/slack`, {
+      chatId: "C1",
+      phase: "thinking",
+    });
+
+    expect(slack.sendSlackAgentSessionStatus).toHaveBeenCalledTimes(1);
     expect(slack.sendSlackReply).not.toHaveBeenCalled();
   });
 
-  test("a typing payload to Slack falls through to deliver (no typing capability)", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/slack`,
-      payload({ chatAction: "typing", text: "hi" }),
-    );
-    expect(slack.sendSlackReply).toHaveBeenCalledTimes(1);
+  test("a channel with no activity indicator resolves quietly", async () => {
+    const result = await setChannelActivity(`${BASE}/deliver/whatsapp`, {
+      chatId: "123",
+      phase: "thinking",
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(slack.sendSlackReply).not.toHaveBeenCalled();
   });
 
-  test("slackStream routes to sendSlackStreamOp ahead of the text path", async () => {
-    const result = await deliverDirect(
+  test("sendChannelStreamOp reaches Slack without touching the text path", async () => {
+    const result = await sendChannelStreamOp(
       `${BASE}/deliver/slack?threadTs=1700.5`,
-      payload({
-        text: "ignored while streaming",
-        slackStream: { action: "start", threadTs: "1700.5" },
-      }),
+      "C1",
+      { action: "start", threadTs: "1700.5", markdownText: "hi" },
     );
     expect(slack.sendSlackStreamOp).toHaveBeenCalledTimes(1);
     expect(slack.sendSlackStreamOp.mock.calls[0]).toEqual([
       "C1",
-      { action: "start", threadTs: "1700.5" },
+      { action: "start", threadTs: "1700.5", markdownText: "hi" },
     ]);
     expect(slack.sendSlackReply).not.toHaveBeenCalled();
     expect(result).toEqual({ ok: true, ts: "stream-ts" });
@@ -191,22 +193,87 @@ describe("Slack sub-operation selection", () => {
 });
 
 describe("capability gating across channels", () => {
-  test("a reaction payload to Telegram falls through to deliver (no sendReaction)", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/telegram`,
-      payload({
-        text: "hi",
-        reaction: { action: "add", name: "x", messageTs: "1" },
+  test("Slack renders a muted edit as its own context block", async () => {
+    await editChannelMessage(`${BASE}/deliver/slack`, {
+      chatId: "C1",
+      messageId: "1700.5",
+      text: "This approval request has been resolved.",
+      emphasis: "muted",
+    });
+
+    // The producer asked for a settled message and named no markup. Slack
+    // decides that means a context block.
+    const [, , , options] = slack.updateSlackMessage.mock.calls[0]!;
+    expect((options as { blocks?: unknown[] }).blocks).toEqual([
+      {
+        type: "context",
+        elements: [
+          {
+            type: "mrkdwn",
+            text: "This approval request has been resolved.",
+          },
+        ],
+      },
+    ]);
+  });
+
+  test("an edit with no emphasis carries no channel markup", async () => {
+    await editChannelMessage(`${BASE}/deliver/slack`, {
+      chatId: "C1",
+      messageId: "1700.5",
+      text: "revised",
+    });
+
+    const [, , , options] = slack.updateSlackMessage.mock.calls[0]!;
+    expect((options as { blocks?: unknown[] }).blocks).toBeUndefined();
+  });
+
+  test("editChannelMessage now reaches Telegram, not only Slack", async () => {
+    // The capability gate is what let Telegram gain this: no caller changed,
+    // the transport grew the method.
+    await editChannelMessage(`${BASE}/deliver/telegram`, {
+      chatId: "123",
+      messageId: "456",
+      text: "revised",
+    });
+
+    expect(telegram.editTelegramMessage).toHaveBeenCalledTimes(1);
+    expect(telegram.sendTelegramReply).not.toHaveBeenCalled();
+  });
+
+  test("a channel that cannot revise a sent message resolves quietly", async () => {
+    // Discord has no `edit` yet. A channel without the method is not a failed
+    // delivery: nothing is attempted, nothing throws, and no fresh message is
+    // posted in place of the revision.
+    expect(
+      await editChannelMessage(`${BASE}/deliver/discord`, {
+        chatId: "C1",
+        messageId: "1",
+        text: "revised",
       }),
-    );
-    expect(telegram.sendTelegramReply).toHaveBeenCalledTimes(1);
+    ).toEqual({ ok: true });
+    expect(discord.sendDiscordReply).not.toHaveBeenCalled();
   });
 
-  test("typing to Telegram routes to its typing indicator", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/telegram`,
-      payload({ chatAction: "typing" }),
-    );
+  test("the activity capability is read from the transport, not the channel name", () => {
+    // The gate in background-dispatch asks this rather than testing
+    // `sourceChannel === "slack"`, so a channel that implements the method
+    // starts showing an indicator without a caller being changed. All three
+    // answer the same question now, which is the point of the single method:
+    // Slack holds its indicator and the other two re-assert theirs, and a
+    // caller cannot tell the difference.
+    expect(supportsChannelActivity(`${BASE}/deliver/slack`)).toBe(true);
+    expect(supportsChannelActivity(`${BASE}/deliver/telegram`)).toBe(true);
+    expect(supportsChannelActivity(`${BASE}/deliver/discord`)).toBe(true);
+    expect(supportsChannelActivity(`${BASE}/deliver/whatsapp`)).toBe(false);
+  });
+
+  test("setChannelActivity reaches Telegram's typing indicator", async () => {
+    await setChannelActivity(`${BASE}/deliver/telegram`, {
+      chatId: "123",
+      phase: "thinking",
+    });
+
     expect(telegram.sendTelegramTypingIndicator).toHaveBeenCalledTimes(1);
   });
 
@@ -244,26 +311,24 @@ describe("capability gating across channels", () => {
     });
   });
 
-  test("a typing payload to Discord falls through to deliver (no sendTyping)", async () => {
-    // Only the Telegram heartbeat produces `chatAction: "typing"`, and it is
-    // gated on sourceChannel === "telegram", so Discord can never receive one.
-    // The transport implements no sendTyping, so this falls through.
-    await deliverDirect(
-      `${BASE}/deliver/discord`,
-      payload({ chatAction: "typing", text: "hi" }),
-    );
-    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+  test("setChannelActivity reaches Discord's typing indicator", async () => {
+    await setChannelActivity(`${BASE}/deliver/discord`, {
+      chatId: "999",
+      phase: "thinking",
+    });
+
+    expect(discord.sendDiscordTypingIndicator).toHaveBeenCalledTimes(1);
   });
 
-  test("a Slack-only stream payload to Discord falls through to deliver", async () => {
-    await deliverDirect(
-      `${BASE}/deliver/discord`,
-      payload({
-        text: "hi",
-        slackStream: { action: "start", threadTs: "1700.5" },
-      }),
-    );
-    expect(discord.sendDiscordReply).toHaveBeenCalledTimes(1);
+  test("a channel that cannot stream resolves quietly, and posts nothing", async () => {
+    const result = await sendChannelStreamOp(`${BASE}/deliver/discord`, "999", {
+      action: "start",
+      threadTs: "1700.5",
+      markdownText: "hi",
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(discord.sendDiscordReply).not.toHaveBeenCalled();
   });
 });
 

package/src/messaging/providers/channel-transport.ts

@@ -1,8 +1,10 @@
 import type {
   ChannelDeliveryResult,
   ChannelReplyPayload,
+  SlackStreamOp,
 } from "@vellumai/gateway-client";
 
+import type { AssistantActivityPhase } from "../../api/index.js";
 import type { ChannelId } from "../../channels/types.js";
 
 /**
@@ -15,15 +17,69 @@ export interface CallbackContext {
   readonly params: Readonly<Record<string, string>>;
 }
 
+/**
+ * How busy the assistant is in one conversation, for the channel to show.
+ *
+ * `phase` is the daemon's own activity phase rather than a channel's word for
+ * it, so every channel is told the same lifecycle and decides how to render
+ * it. A channel whose indicator expires on its own re-sends while the busy
+ * phases last; a channel whose indicator holds sets it once and clears it on
+ * `idle`. Neither shape leaks into what the caller says.
+ */
+export interface ActivityTarget {
+  readonly chatId: string;
+  readonly phase: AssistantActivityPhase;
+  /**
+   * Who started the turn. Channels that attribute a session to a person read
+   * it when the session is created, and ignore it afterwards.
+   */
+  readonly initiatorUserId?: string;
+}
+
+/**
+ * Whether a phase means a turn is actually running.
+ *
+ * A channel with a plain busy indicator shows it for these and nothing else.
+ * `awaiting_confirmation` is deliberately not one: an approval is waiting on a
+ * person, and a typing bubble there promises output that is not coming.
+ */
+export function isBusyActivityPhase(phase: AssistantActivityPhase): boolean {
+  return (
+    phase === "thinking" || phase === "streaming" || phase === "tool_running"
+  );
+}
+
+/**
+ * An existing message to replace in place, and what to replace it with.
+ *
+ * `messageId` is the target in the channel's own id space, the same way
+ * `chatId` is. `renderRichly` and `emphasis` are the rendering inputs the edit
+ * carries, so a replacement renders the way the original did rather than
+ * degrading to plain text.
+ */
+export interface EditTarget {
+  readonly chatId: string;
+  readonly messageId: string;
+  readonly text: string;
+  readonly renderRichly?: boolean;
+  /**
+   * How prominent the replacement should read. Surface-agnostic, the way
+   * `ApprovalActionOption.emphasis` is: each channel translates it to its own
+   * token, and one with no equivalent renders plain text. `muted` marks a
+   * message as settled rather than current.
+   */
+  readonly emphasis?: "muted";
+}
+
 /**
  * Direct outbound delivery for one channel, wrapping the channel's provider-API
  * send functions behind a uniform surface. Transports are registered statically
  * (delivery runs in non-daemon contexts) and dispatched by channel, resolved
  * from the gateway callback URL via `callback-routing.ts`.
  *
- * The dispatcher routes a payload to the optional sub-operation methods when the
- * matching payload field is set and the method exists; otherwise it calls
- * `deliver`. A transport only implements the sub-operations it supports.
+ * Each operation takes its own parameters and is reached through its own entry
+ * point; a transport implements only the operations its channel supports, so
+ * an absent method is an absent capability.
  */
 export interface ChannelTransport {
   /** Canonical source channel id, e.g. `"slack"`. */
@@ -35,27 +91,55 @@ export interface ChannelTransport {
     payload: ChannelReplyPayload,
   ): Promise<ChannelDeliveryResult>;
 
-  /** Send a typing indicator. Routed when `payload.chatAction === "typing"`. */
-  sendTyping?(
+  /**
+   * Replace a message the assistant already sent.
+   *
+   * Distinct from `deliver`, which always posts something new. A channel that
+   * cannot revise a sent message omits this, and a caller that needs the
+   * revision to be visible has to post instead of silently doing nothing.
+   *
+   * An implementation must not fall back to posting when the edit fails. The
+   * original would remain beside the replacement, which reads as the assistant
+   * answering twice.
+   */
+  edit?(
     ctx: CallbackContext,
-    payload: ChannelReplyPayload,
+    target: EditTarget,
   ): Promise<ChannelDeliveryResult>;
 
-  /** Add an emoji reaction. Routed when `payload.reaction` is set. */
-  sendReaction?(
+  /**
+   * Show how busy the assistant is, in whatever form the channel has.
+   *
+   * One capability rather than one per indicator shape: a self-expiring typing
+   * bubble and a status that holds until cleared answer the same question, and
+   * splitting them by how the channel keeps them alive forces every caller to
+   * know which channel it is talking to. A channel without any such affordance
+   * omits the method, so implementing it is the whole of declaring it.
+   */
+  setActivity?(
     ctx: CallbackContext,
-    payload: ChannelReplyPayload,
+    target: ActivityTarget,
   ): Promise<ChannelDeliveryResult>;
 
-  /** Update an assistant-thread status surface. Routed when `payload.assistantThreadStatus` is set. */
-  setThreadStatus?(
-    ctx: CallbackContext,
-    payload: ChannelReplyPayload,
-  ): Promise<ChannelDeliveryResult>;
+  /**
+   * How often a busy indicator must be re-asserted to stay visible, for a
+   * channel whose indicator expires on its own.
+   *
+   * Omitted by a channel whose indicator holds until it is changed, which is
+   * how a caller knows to set it once rather than run a timer. Declaring the
+   * cadence here keeps the caller from having to know which channel it is.
+   */
+  readonly activityRefreshMs?: number;
 
-  /** Perform one streaming operation. Routed when `payload.slackStream` is set. */
+  /**
+   * Advance a streamed reply: open it, add to it, or close it.
+   *
+   * A channel that can only post a finished message omits this, and the
+   * caller falls back to delivering the reply whole.
+   */
   streamReply?(
     ctx: CallbackContext,
-    payload: ChannelReplyPayload,
+    chatId: string,
+    op: SlackStreamOp,
   ): Promise<ChannelDeliveryResult>;
 }

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

@@ -210,3 +210,19 @@ export async function sendDiscordAttachments(
     totalCount: attachments.length,
   };
 }
+
+/**
+ * Show the Discord typing indicator in a channel.
+ *
+ * Discord expires it after about ten seconds, so a caller that wants it to
+ * persist re-sends on a timer rather than clearing it; there is no stop route.
+ */
+export async function sendDiscordTypingIndicator(
+  target: DiscordSendTarget,
+): Promise<void> {
+  await callDiscordApi(
+    "POST",
+    `/channels/${encodeURIComponent(target.channelId)}/typing`,
+    {},
+  );
+}

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

@@ -5,9 +5,14 @@ import type {
   CallbackContext,
   ChannelTransport,
 } from "../channel-transport.js";
+import { isBusyActivityPhase } from "../channel-transport.js";
 import { openDiscordDmChannel } from "./api.js";
 import type { DiscordSendTarget } from "./send.js";
-import { sendDiscordAttachments, sendDiscordReply } from "./send.js";
+import {
+  sendDiscordAttachments,
+  sendDiscordReply,
+  sendDiscordTypingIndicator,
+} from "./send.js";
 
 const log = getLogger("discord-transport");
 
@@ -43,6 +48,23 @@ async function sendTarget(
 export const discordTransport: ChannelTransport = {
   channel: "discord",
 
+  // Discord clears a typing indicator after ten seconds.
+  activityRefreshMs: 8_000,
+
+  async setActivity(ctx, target) {
+    // Discord's typing indicator expires by itself after ten seconds, so a
+    // phase that is not running needs no clearing call.
+    if (!isBusyActivityPhase(target.phase)) {
+      return { ok: true };
+    }
+    await sendDiscordTypingIndicator(await sendTarget(ctx, target.chatId));
+    log.debug(
+      { chatId: target.chatId, phase: target.phase },
+      "Discord typing indicator delivered (direct)",
+    );
+    return { ok: true };
+  },
+
   async deliver(ctx, payload) {
     const { chatId, text, attachments, approval } = payload;
     const target = await sendTarget(ctx, chatId);

package/src/messaging/providers/index.ts

@@ -11,12 +11,18 @@
 import type {
   ChannelDeliveryResult,
   ChannelReplyPayload,
+  SlackStreamOp,
 } from "@vellumai/gateway-client";
 
 import { a2aTransport } from "./a2a/transport.js";
 import type { DirectDeliveryChannel } from "./callback-routing.js";
 import { channelForCallback } from "./callback-routing.js";
-import type { CallbackContext, ChannelTransport } from "./channel-transport.js";
+import type {
+  ActivityTarget,
+  CallbackContext,
+  ChannelTransport,
+  EditTarget,
+} from "./channel-transport.js";
 import { discordTransport } from "./discord/transport.js";
 import { slackTransport } from "./slack/transport.js";
 import { telegramTransport } from "./telegram-bot/transport.js";
@@ -45,6 +51,81 @@ export function getTransportForCallback(
   return channel ? TRANSPORTS[channel] : undefined;
 }
 
+/**
+ * Whether the channel this callback addresses can show how busy the assistant
+ * is.
+ *
+ * Asks the transport rather than the channel id, so a channel that gains the
+ * method starts being asked without a caller being told about it.
+ */
+export function supportsChannelActivity(callbackUrl: string): boolean {
+  return getTransportForCallback(callbackUrl)?.setActivity !== undefined;
+}
+
+/**
+ * How often this channel's busy indicator has to be re-asserted, or
+ * `undefined` when it holds until changed and one call is enough.
+ */
+export function channelActivityRefreshMs(
+  callbackUrl: string,
+): number | undefined {
+  return getTransportForCallback(callbackUrl)?.activityRefreshMs;
+}
+
+/**
+ * Show how busy the assistant is on the channel this callback addresses.
+ *
+ * Resolves to nothing when the channel has no such affordance, which is the
+ * ordinary case rather than a failure: the indicator is decoration, and a
+ * channel that cannot show one is not degraded by its absence.
+ */
+export async function setChannelActivity(
+  callbackUrl: string,
+  target: ActivityTarget,
+): Promise<ChannelDeliveryResult> {
+  const transport = getTransportForCallback(callbackUrl);
+  if (!transport?.setActivity) {
+    return { ok: true };
+  }
+  return transport.setActivity(callbackContext(callbackUrl), target);
+}
+
+/**
+ * Replace a message the assistant already sent.
+ *
+ * Returns `ok` without acting when the channel cannot revise a sent message,
+ * matching the other capability entry points: an absent method is an absent
+ * capability, not an error.
+ */
+export async function editChannelMessage(
+  callbackUrl: string,
+  target: EditTarget,
+): Promise<ChannelDeliveryResult> {
+  const transport = getTransportForCallback(callbackUrl);
+  if (!transport?.edit) {
+    return { ok: true };
+  }
+  return transport.edit(callbackContext(callbackUrl), target);
+}
+
+/**
+ * Advance a streamed reply on the channel this callback addresses.
+ *
+ * Resolves to nothing when the channel cannot stream, so a caller that wants a
+ * streamed reply learns it has to send the whole thing instead.
+ */
+export async function sendChannelStreamOp(
+  callbackUrl: string,
+  chatId: string,
+  op: SlackStreamOp,
+): Promise<ChannelDeliveryResult> {
+  const transport = getTransportForCallback(callbackUrl);
+  if (!transport?.streamReply) {
+    return { ok: true };
+  }
+  return transport.streamReply(callbackContext(callbackUrl), chatId, op);
+}
+
 function callbackContext(callbackUrl: string): CallbackContext {
   const params: Record<string, string> = {};
   try {
@@ -74,9 +155,8 @@ export function isDirectDelivery(callbackUrl: string): boolean {
  * Deliver a channel reply directly to the provider API, bypassing the gateway
  * HTTP proxy. Callers MUST check `isDirectDelivery()` first.
  *
- * Sub-operations (reaction, thread status, typing) route to the transport's
- * optional method when both the payload field and the method are present;
- * otherwise the reply is delivered as text / approval / attachments.
+ * Delivers the reply itself: text, approval card, attachments. Every other
+ * operation a transport supports is reached through its own entry point.
  */
 export async function deliverDirect(
   callbackUrl: string,
@@ -90,17 +170,5 @@ export async function deliverDirect(
   }
 
   const ctx = callbackContext(callbackUrl);
-  if (payload.slackStream && transport.streamReply) {
-    return transport.streamReply(ctx, payload);
-  }
-  if (payload.reaction && transport.sendReaction) {
-    return transport.sendReaction(ctx, payload);
-  }
-  if (payload.assistantThreadStatus && transport.setThreadStatus) {
-    return transport.setThreadStatus(ctx, payload);
-  }
-  if (payload.chatAction === "typing" && transport.sendTyping) {
-    return transport.sendTyping(ctx, payload);
-  }
   return transport.deliver(ctx, payload);
 }

package/src/messaging/providers/slack/message-metadata.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import type { ProviderMessageMetadata } from "../../provider-message-metadata.js";
+
 /**
  * Typed Slack message metadata stored flat in the `messages.metadata` column
  * alongside whatever other top-level keys the broader metadata envelope
@@ -288,6 +290,49 @@ export function readSlackMetadataFromMessageMetadata(
   return opts?.allowFlatLegacy ? readSlackMetadata(metadata) : null;
 }
 
+/**
+ * Present a Slack row's stored metadata as the channel-neutral shape.
+ *
+ * `channelTs` is the row's own provider id and `targetChannelTs` the id of the
+ * message a reaction was attached to. Both are Slack `ts` strings, which is a
+ * Slack detail of the id format, not of the fact.
+ *
+ * The rest of Slack's envelope (file markers, timezone labels, channel name)
+ * stays there and is read from there by the Slack transcript renderer, which
+ * is a provider renderer by design.
+ */
+export function slackMetadataAsProviderMetadata(
+  meta: SlackMessageMetadata,
+): ProviderMessageMetadata {
+  return {
+    source: "slack",
+    conversationExternalId: meta.channelId,
+    // A reaction row stores the reacted message's ts in `channelTs`, which is
+    // its target rather than an id of its own.
+    ...(meta.eventKind === "reaction" ? {} : { messageId: meta.channelTs }),
+    ...(meta.actorExternalUserId
+      ? { actorExternalId: meta.actorExternalUserId }
+      : {}),
+    ...(meta.threadTs ? { threadId: meta.threadTs } : {}),
+    ...(meta.displayName ? { displayName: meta.displayName } : {}),
+    eventKind: meta.eventKind,
+    ...(meta.reaction
+      ? {
+          reaction: {
+            targetMessageId: meta.reaction.targetChannelTs,
+            emoji: meta.reaction.emoji,
+            op: meta.reaction.op,
+            ...(meta.reaction.actorDisplayName
+              ? { actorDisplayName: meta.reaction.actorDisplayName }
+              : {}),
+          },
+        }
+      : {}),
+    ...(meta.editedAt !== undefined ? { editedAt: meta.editedAt } : {}),
+    ...(meta.deletedAt !== undefined ? { deletedAt: meta.deletedAt } : {}),
+  };
+}
+
 /**
  * Serialize `SlackMessageMetadata` to a JSON string suitable for a fresh
  * write to the `messages.metadata` column. Use `mergeSlackMetadata` when an