@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

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

@@ -6,6 +6,9 @@
  * classification, and payload shapes follow Slack Web API conventions.
  */
 
+import type { KnownBlock } from "@slack/types";
+import type { SlackStreamTask } from "@vellumai/gateway-client";
+
 import { credentialKey } from "../../../security/credential-key.js";
 import { getSecureKeyAsync } from "../../../security/secure-keys.js";
 import { getLogger } from "../../../util/logger.js";
@@ -267,6 +270,113 @@ async function callSlackApiGet(
   );
 }
 
+// ---------------------------------------------------------------------------
+// Streaming (chat.startStream / chat.appendStream / chat.stopStream)
+// ---------------------------------------------------------------------------
+
+/** Slack caps `markdown_text` at 12,000 characters per stream call. */
+export const SLACK_STREAM_MARKDOWN_LIMIT = 12_000;
+
+/**
+ * A `task_update` streaming chunk. Identical in shape to the Slack task card
+ * block, used to render plan progress while a stream is open.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.appendStream/
+ */
+function toTaskUpdateChunks(
+  tasks: readonly SlackStreamTask[] | undefined,
+): Record<string, unknown>[] | undefined {
+  if (!tasks || tasks.length === 0) return undefined;
+  return tasks.map((task) => ({
+    type: "task_update",
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    ...(task.details ? { details: task.details } : {}),
+    ...(task.output ? { output: task.output } : {}),
+  }));
+}
+
+/**
+ * Open a streamed reply on a thread, returning its `ts` for subsequent
+ * appends. `task_display_mode: "plan"` renders task chunks as a native plan.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.startStream/
+ */
+export async function startSlackStream(params: {
+  channel: string;
+  threadTs: string;
+  markdownText?: string;
+  taskDisplayMode?: "plan";
+  tasks?: readonly SlackStreamTask[];
+  recipientUserId?: string;
+  recipientTeamId?: string;
+}): Promise<string | undefined> {
+  const body: Record<string, unknown> = {
+    channel: params.channel,
+    thread_ts: params.threadTs,
+  };
+  if (params.markdownText) body.markdown_text = params.markdownText;
+  if (params.taskDisplayMode) body.task_display_mode = params.taskDisplayMode;
+  // Channel streams must name the reader; DMs infer it and omit both fields.
+  if (params.recipientUserId) body.recipient_user_id = params.recipientUserId;
+  if (params.recipientTeamId) body.recipient_team_id = params.recipientTeamId;
+  const chunks = toTaskUpdateChunks(params.tasks);
+  if (chunks) body.chunks = chunks;
+
+  const data = await callSlackApi("chat.startStream", body);
+  return data.ts;
+}
+
+/**
+ * Append markdown and/or task chunks to an open stream. Slack accepts an append
+ * carrying either `markdown_text` or `chunks`, so a task-only append advances
+ * the plan block without new body text.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.appendStream/
+ */
+export async function appendSlackStream(params: {
+  channel: string;
+  streamTs: string;
+  markdownText?: string;
+  tasks?: readonly SlackStreamTask[];
+}): Promise<void> {
+  const body: Record<string, unknown> = {
+    channel: params.channel,
+    ts: params.streamTs,
+  };
+  if (params.markdownText) body.markdown_text = params.markdownText;
+  const chunks = toTaskUpdateChunks(params.tasks);
+  if (chunks) body.chunks = chunks;
+
+  await callSlackApi("chat.appendStream", body);
+}
+
+/**
+ * Finalize a stream, optionally rendering rich Block Kit blocks at the bottom
+ * of the message. Blocks are accepted only here, not on append.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.stopStream/
+ */
+export async function stopSlackStream(params: {
+  channel: string;
+  streamTs: string;
+  markdownText?: string;
+  blocks?: readonly KnownBlock[];
+  tasks?: readonly SlackStreamTask[];
+}): Promise<void> {
+  const body: Record<string, unknown> = {
+    channel: params.channel,
+    ts: params.streamTs,
+  };
+  if (params.markdownText) body.markdown_text = params.markdownText;
+  if (params.blocks && params.blocks.length > 0) body.blocks = params.blocks;
+  const chunks = toTaskUpdateChunks(params.tasks);
+  if (chunks) body.chunks = chunks;
+
+  await callSlackApi("chat.stopStream", body);
+}
+
 function normalizeSlackString(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();

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

@@ -31,6 +31,12 @@ mock.module("./api.js", () => ({
     }
   },
   uploadToSlackUrl: async () => {},
+  startSlackStream: (params: { markdownText?: string }) =>
+    callSlackApiMock("chat.startStream", { ...params }),
+  appendSlackStream: (params: { markdownText?: string }) =>
+    callSlackApiMock("chat.appendStream", { ...params }),
+  stopSlackStream: (params: { markdownText?: string }) =>
+    callSlackApiMock("chat.stopStream", { ...params }),
 }));
 
 const { SlackApiError } = await import("./api.js");
@@ -274,3 +280,82 @@ describe("sendSlackReply post path", () => {
     expect(callSlackApiMock).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("sendSlackReply approval fallback", () => {
+  const approval = {
+    requestId: "req-123",
+    actions: [
+      { id: "approve_once", label: "Approve once" },
+      { id: "reject", label: "Reject" },
+    ],
+    plainTextFallback: 'Reply "ABC123 approve" or "ABC123 reject"',
+  };
+  const blocks: KnownBlock[] = [
+    { type: "section", text: { type: "mrkdwn", text: "Approve tool: bash" } },
+  ];
+
+  beforeEach(() => {
+    callSlackApiMock.mockReset();
+    callSlackApiMock.mockImplementation(async () => ({ ok: true }));
+  });
+
+  test("block-free retry re-attaches plain-text reply instructions", async () => {
+    // Dropping an approval's blocks drops its buttons — the retry text must
+    // carry the reply instructions so the recipient can still act.
+    callSlackApiMock
+      .mockImplementationOnce(async () => {
+        throw new SlackApiError("invalid_blocks");
+      })
+      .mockImplementationOnce(async () => ({
+        ok: true,
+        ts: "1700000000.000400",
+      }));
+
+    const result = await sendSlackReply("C123", "Approve tool: bash", {
+      blocks,
+      approval,
+    });
+
+    expect(result).toEqual({ ok: true, ts: "1700000000.000400" });
+    expect(callSlackApiMock).toHaveBeenCalledTimes(2);
+    expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "chat.postMessage", {
+      channel: "C123",
+      text: 'Approve tool: bash\n\nReply "ABC123 approve" or "ABC123 reject"',
+    });
+  });
+
+  test("retry text is unchanged when it already contains the instructions", async () => {
+    callSlackApiMock
+      .mockImplementationOnce(async () => {
+        throw new SlackApiError("msg_blocks_too_long");
+      })
+      .mockImplementationOnce(async () => ({
+        ok: true,
+        ts: "1700000000.000500",
+      }));
+
+    const text = `Approve tool: bash\n\n${approval.plainTextFallback}`;
+    await sendSlackReply("C123", text, { blocks, approval });
+
+    expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "chat.postMessage", {
+      channel: "C123",
+      text,
+    });
+  });
+
+  test("approval without usable instructions is never retried bare", async () => {
+    // A block-free approval with no reply instructions gives the recipient no
+    // way to respond — fail the delivery instead so it surfaces as an error.
+    callSlackApiMock.mockImplementationOnce(async () => {
+      throw new SlackApiError("invalid_blocks");
+    });
+
+    await expect(
+      sendSlackReply("C123", "Approve tool: bash", {
+        blocks,
+        approval: { ...approval, plainTextFallback: "  " },
+      }),
+    ).rejects.toThrow();
+    expect(callSlackApiMock).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -7,16 +7,22 @@
  */
 
 import type { Button, KnownBlock } from "@slack/types";
-import type { ApprovalUIMetadata } from "@vellumai/gateway-client";
+import type {
+  ApprovalUIMetadata,
+  SlackStreamOp,
+} from "@vellumai/gateway-client";
 
 import { getAttachmentContent } from "../../../persistence/attachments-store.js";
 import type { RuntimeAttachmentMetadata } from "../../../runtime/http-types.js";
 import { getLogger } from "../../../util/logger.js";
 import {
+  appendSlackStream,
   callSlackApi,
   callSlackApiForm,
   completeSlackUpload,
   SlackApiError,
+  startSlackStream,
+  stopSlackStream,
   uploadToSlackUrl,
 } from "./api.js";
 import { renderSlackBlocks } from "./render.js";
@@ -145,13 +151,15 @@ export interface SlackSendResult {
  * Those errors fault the Block Kit payload, not the target — the retry repeats
  * the *same* operation (same `chat.update` ts, same `chat.postMessage` thread)
  * without blocks, so it edits/posts in place rather than spawning a second
- * message. Any other error propagates to the caller.
+ * message. `fallbackText` replaces the message text on that retry (used to
+ * re-attach reply instructions whose Block Kit equivalent was dropped). Any
+ * other error propagates to the caller.
  */
 async function sendWithBlockFallback(
   method: string,
   baseBody: Record<string, unknown>,
   blocks: KnownBlock[],
-  options: { fallbackWithoutBlocks: boolean },
+  options: { fallbackWithoutBlocks: boolean; fallbackText?: string },
 ): Promise<SlackSendResult> {
   try {
     const result = await callSlackApi(
@@ -171,13 +179,36 @@ async function sendWithBlockFallback(
         { method, slackError: err.slackError },
         "Slack rejected blocks; retrying without blocks",
       );
-      const result = await callSlackApi(method, baseBody);
+      const retryBody =
+        options.fallbackText !== undefined
+          ? { ...baseBody, text: options.fallbackText }
+          : baseBody;
+      const result = await callSlackApi(method, retryBody);
       return { ok: true, ts: result.ts };
     }
     throw err;
   }
 }
 
+/**
+ * Text for the block-free retry of an approval prompt. Dropping an approval's
+ * blocks removes its Approve/Reject buttons, so the retry re-attaches the
+ * plain-text reply instructions to keep the message actionable. Returns
+ * `undefined` when the approval has no usable instructions — such a prompt
+ * must not be retried bare, since a message with no way to respond is worse
+ * than a failed delivery the delivery layer can surface.
+ */
+function buildApprovalFallbackText(
+  text: string,
+  approval: ApprovalUIMetadata,
+): string | undefined {
+  const instructions = approval.plainTextFallback.trim();
+  if (instructions.length === 0) {
+    return undefined;
+  }
+  return text.includes(instructions) ? text : `${text}\n\n${instructions}`;
+}
+
 /**
  * Send a Slack text message with optional Block Kit formatting.
  *
@@ -213,51 +244,92 @@ export async function sendSlackReply(
   }
 
   const postBase: Record<string, unknown> = { channel: chatId, text };
-  if (options?.threadTs) postBase.thread_ts = options.threadTs;
+  if (options?.threadTs) {
+    postBase.thread_ts = options.threadTs;
+  }
+
+  // Approval prompts carry their action buttons in `blocks`. When Slack
+  // rejects the payload, the block-free retry re-attaches the plain-text
+  // reply instructions so the recipient can still act by text reply; an
+  // approval without usable instructions is never retried bare.
+  const approvalFallbackText = options?.approval
+    ? buildApprovalFallbackText(text, options.approval)
+    : undefined;
+  const fallbackOptions = {
+    fallbackWithoutBlocks:
+      !options?.approval || approvalFallbackText !== undefined,
+    fallbackText: approvalFallbackText,
+  };
 
   if (options?.ephemeral) {
-    if (!options.user)
+    if (!options.user) {
       throw new Error("user is required for ephemeral messages");
+    }
     return sendWithBlockFallback(
       "chat.postEphemeral",
       { ...postBase, user: options.user },
       blocks,
-      { fallbackWithoutBlocks: !options.approval },
+      fallbackOptions,
     );
   }
 
-  // Approval prompts carry their action buttons in `blocks`; dropping them when
-  // Slack rejects the payload would post a card with no way to respond, so only
-  // non-approval posts fall back to a block-free retry.
   const result = await sendWithBlockFallback(
     "chat.postMessage",
     postBase,
     blocks,
-    {
-      fallbackWithoutBlocks: !options?.approval,
-    },
+    fallbackOptions,
   );
   log.info({ chatId, hasThreadTs: !!options?.threadTs }, "Slack message sent");
   return result;
 }
 
 /**
- * Send a typing indicator placeholder message to Slack.
- * Returns the placeholder message ts for later update.
+ * Execute one Slack streaming operation against a channel, returning the
+ * stream `ts` so the caller can carry it across `append`/`stop` calls. `start`
+ * mints a new `ts`; `append` and `stop` echo the one they were given.
+ *
+ * Throwing on failure is intentional: the streaming session decides whether to
+ * abandon the stream and let durable delivery post the full reply.
  */
-export async function sendSlackTypingIndicator(
-  chatId: string,
-  threadTs?: string,
-): Promise<string | undefined> {
-  const body: Record<string, string> = { channel: chatId, text: "\u2026" };
-  if (threadTs) body.thread_ts = threadTs;
-
-  const result = await callSlackApi("chat.postMessage", body);
-  log.debug(
-    { chatId, placeholderTs: result.ts, hasThreadTs: !!threadTs },
-    "Slack typing placeholder sent",
-  );
-  return result.ts;
+export async function sendSlackStreamOp(
+  channel: string,
+  op: SlackStreamOp,
+): Promise<SlackSendResult> {
+  switch (op.action) {
+    case "start": {
+      const ts = await startSlackStream({
+        channel,
+        threadTs: op.threadTs,
+        markdownText: op.markdownText,
+        taskDisplayMode: op.taskDisplayMode,
+        tasks: op.tasks,
+        recipientUserId: op.recipientUserId,
+        recipientTeamId: op.recipientTeamId,
+      });
+      log.info({ channel, ts }, "Slack stream started");
+      return { ok: ts !== undefined, ts };
+    }
+    case "append": {
+      await appendSlackStream({
+        channel,
+        streamTs: op.streamTs,
+        markdownText: op.markdownText,
+        tasks: op.tasks,
+      });
+      return { ok: true, ts: op.streamTs };
+    }
+    case "stop": {
+      await stopSlackStream({
+        channel,
+        streamTs: op.streamTs,
+        markdownText: op.markdownText,
+        blocks: op.blocks,
+        tasks: op.tasks,
+      });
+      log.info({ channel, ts: op.streamTs }, "Slack stream stopped");
+      return { ok: true, ts: op.streamTs };
+    }
+  }
 }
 
 /**

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

@@ -7,7 +7,7 @@ import {
   sendSlackAttachments,
   sendSlackReaction,
   sendSlackReply,
-  sendSlackTypingIndicator,
+  sendSlackStreamOp,
 } from "./send.js";
 
 const log = getLogger("slack-transport");
@@ -54,18 +54,6 @@ export const slackTransport: ChannelTransport = {
     return { ok: true, ts: sentTs };
   },
 
-  async sendTyping(ctx, payload) {
-    const placeholderTs = await sendSlackTypingIndicator(
-      payload.chatId,
-      ctx.params.threadTs,
-    );
-    log.debug(
-      { chatId: payload.chatId },
-      "Slack typing indicator delivered (direct)",
-    );
-    return { ok: true, ts: placeholderTs };
-  },
-
   async sendReaction(_ctx, payload) {
     const reaction = payload.reaction;
     if (!reaction) return { ok: true };
@@ -89,4 +77,10 @@ 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);
+  },
 };

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

@@ -37,10 +37,12 @@ const WHATSAPP_VIDEO_MIME_PREFIXES = ["video/mp4", "video/3gpp"];
 const WHATSAPP_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
 function resolveMediaType(mimeType: string): WhatsAppMediaType {
-  if (WHATSAPP_IMAGE_MIME_PREFIXES.some((p) => mimeType.startsWith(p)))
+  if (WHATSAPP_IMAGE_MIME_PREFIXES.some((p) => mimeType.startsWith(p))) {
     return "image";
-  if (WHATSAPP_VIDEO_MIME_PREFIXES.some((p) => mimeType.startsWith(p)))
+  }
+  if (WHATSAPP_VIDEO_MIME_PREFIXES.some((p) => mimeType.startsWith(p))) {
     return "video";
+  }
   return "document";
 }
 
@@ -49,33 +51,51 @@ function resolveMediaType(mimeType: string): WhatsAppMediaType {
  * Tries to split on newlines first, then whitespace, then hard-cuts.
  */
 function splitText(text: string, maxLen: number): string[] {
-  if (text.length <= maxLen) return [text];
+  if (text.length <= maxLen) {
+    return [text];
+  }
 
   const chunks: string[] = [];
   let remaining = text;
 
   while (remaining.length > maxLen) {
     let splitIdx = remaining.lastIndexOf("\n", maxLen);
-    if (splitIdx <= 0) splitIdx = remaining.lastIndexOf(" ", maxLen);
-    if (splitIdx <= 0) splitIdx = maxLen;
+    if (splitIdx <= 0) {
+      splitIdx = remaining.lastIndexOf(" ", maxLen);
+    }
+    if (splitIdx <= 0) {
+      splitIdx = maxLen;
+    }
 
     chunks.push(remaining.slice(0, splitIdx));
     remaining = remaining.slice(splitIdx).trimStart();
   }
 
-  if (remaining.length > 0) chunks.push(remaining);
+  if (remaining.length > 0) {
+    chunks.push(remaining);
+  }
   return chunks;
 }
 
+// Deny-intent actions are pinned when the button cap forces a cut — the
+// guardian must always have a button path to refuse/block.
+const WHATSAPP_PINNED_ACTION_IDS = new Set(["reject", "block"]);
+
 /**
  * Select up to WHATSAPP_MAX_BUTTONS actions for WhatsApp interactive buttons.
- * With only approve_once and reject, this limit is never exceeded, but we
- * keep the cap in case future action types are added.
+ * Introduction cards carry four actions, so when the cap forces a cut the
+ * deny-intent actions (reject/block) are preserved and the remaining slots
+ * are filled in order.
  */
 function selectButtons(
   actions: Array<{ id: string; label: string }>,
 ): Array<{ id: string; label: string }> {
-  return actions.slice(0, WHATSAPP_MAX_BUTTONS);
+  if (actions.length <= WHATSAPP_MAX_BUTTONS) {
+    return actions;
+  }
+  const pinned = actions.filter((a) => WHATSAPP_PINNED_ACTION_IDS.has(a.id));
+  const rest = actions.filter((a) => !WHATSAPP_PINNED_ACTION_IDS.has(a.id));
+  return [...rest.slice(0, WHATSAPP_MAX_BUTTONS - pinned.length), ...pinned];
 }
 
 // ---------------------------------------------------------------------------