@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/messaging/providers/index.ts

@@ -11,18 +11,17 @@
 import type {
   ChannelDeliveryResult,
   ChannelReplyPayload,
-  SlackStreamOp,
+  StreamOp,
 } 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 {
+  ActivityTarget,
   CallbackContext,
   ChannelTransport,
   EditTarget,
-  ReactionTarget,
-  ThreadStatus,
 } from "./channel-transport.js";
 import { discordTransport } from "./discord/transport.js";
 import { slackTransport } from "./slack/transport.js";
@@ -53,40 +52,44 @@ export function getTransportForCallback(
 }
 
 /**
- * Whether the channel this callback addresses can show a working indicator.
+ * 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 supportsChannelTyping(callbackUrl: string): boolean {
-  return getTransportForCallback(callbackUrl)?.typing !== undefined;
+export function supportsChannelActivity(callbackUrl: string): boolean {
+  return getTransportForCallback(callbackUrl)?.setActivity !== undefined;
 }
 
 /**
- * Show that the assistant is working on the channel this callback addresses.
+ * 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 sendChannelTyping(
+export async function setChannelActivity(
   callbackUrl: string,
-  chatId: string,
+  target: ActivityTarget,
 ): Promise<ChannelDeliveryResult> {
   const transport = getTransportForCallback(callbackUrl);
-  if (!transport?.typing) {
+  if (!transport?.setActivity) {
     return { ok: true };
   }
-  return transport.typing(callbackContext(callbackUrl), chatId);
+  return transport.setActivity(callbackContext(callbackUrl), target);
 }
 
-/**
- * Add or remove one of the assistant's own reactions on a message.
- *
- * Resolves to nothing when the channel has none, the same as typing: a
- * reaction is an acknowledgement, and a channel that cannot show one is not a
- * failed delivery.
- */
 /**
  * Replace a message the assistant already sent.
  *
@@ -105,34 +108,6 @@ export async function editChannelMessage(
   return transport.edit(callbackContext(callbackUrl), target);
 }
 
-export async function sendChannelReaction(
-  callbackUrl: string,
-  target: ReactionTarget,
-): Promise<ChannelDeliveryResult> {
-  const transport = getTransportForCallback(callbackUrl);
-  if (!transport?.react) {
-    return { ok: true };
-  }
-  return transport.react(callbackContext(callbackUrl), target);
-}
-
-/**
- * Set or clear the channel's status surface.
- *
- * Resolves to nothing when the channel holds none, so a caller does not have
- * to know which channels do.
- */
-export async function setChannelThreadStatus(
-  callbackUrl: string,
-  status: ThreadStatus,
-): Promise<ChannelDeliveryResult> {
-  const transport = getTransportForCallback(callbackUrl);
-  if (!transport?.setThreadStatus) {
-    return { ok: true };
-  }
-  return transport.setThreadStatus(callbackContext(callbackUrl), status);
-}
-
 /**
  * Advance a streamed reply on the channel this callback addresses.
  *
@@ -142,7 +117,7 @@ export async function setChannelThreadStatus(
 export async function sendChannelStreamOp(
   callbackUrl: string,
   chatId: string,
-  op: SlackStreamOp,
+  op: StreamOp,
 ): Promise<ChannelDeliveryResult> {
   const transport = getTransportForCallback(callbackUrl);
   if (!transport?.streamReply) {

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

@@ -28,56 +28,113 @@ 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, updateSlackMessage } =
+const { sendSlackAgentSessionStatus, sendSlackReply, updateSlackMessage } =
   await import("./send.js");
 
-describe("sendSlackAssistantThreadStatus", () => {
+describe("sendSlackAgentSessionStatus", () => {
+  const threadTs = "1700000000.000100";
+
   beforeEach(() => {
     callSlackApiMock.mockReset();
     callSlackApiMock.mockImplementation(async () => ({ ok: true }));
   });
 
-  test("serializes loading messages for Slack assistant thread status", async () => {
-    await sendSlackAssistantThreadStatus(
-      "C123",
-      "1700000000.000100",
-      "is working...",
-      ["Reading files", "Running tests"],
-    );
+  // Every phase, so a mapping that loses one fails here rather than showing
+  // the wrong thing in Slack. `suspended` is the one with teeth: an approval
+  // is waiting on a person, and Slack renders that differently from a turn
+  // that is still running.
+  test.each([
+    ["idle", "active"],
+    ["thinking", "processing"],
+    ["streaming", "processing"],
+    ["tool_running", "processing"],
+    ["awaiting_confirmation", "suspended"],
+  ] as const)("sends %s as the %s session status", async (phase, status) => {
+    await sendSlackAgentSessionStatus({ channel: "C123", phase, threadTs });
 
     expect(callSlackApiMock).toHaveBeenCalledTimes(1);
-    expect(callSlackApiMock).toHaveBeenCalledWith(
-      "assistant.threads.setStatus",
-      {
-        channel_id: "C123",
-        thread_ts: "1700000000.000100",
-        status: "is working...",
-        loading_messages: ["Reading files", "Running tests"],
-      },
-    );
+    expect(callSlackApiMock).toHaveBeenCalledWith("agents.sessions.setStatus", {
+      channel_id: "C123",
+      status,
+      thread_ts: threadTs,
+    });
+  });
+
+  test("carries the initiator, which Slack reads only when it opens the session", async () => {
+    await sendSlackAgentSessionStatus({
+      channel: "C123",
+      phase: "thinking",
+      threadTs,
+      initiatorUserId: "U0READER",
+    });
+
+    expect(callSlackApiMock).toHaveBeenCalledWith("agents.sessions.setStatus", {
+      channel_id: "C123",
+      status: "processing",
+      thread_ts: threadTs,
+      initiator_user_id: "U0READER",
+    });
+  });
+
+  test("omits thread_ts in a conversation the app has not threaded", async () => {
+    await sendSlackAgentSessionStatus({ channel: "D123", phase: "thinking" });
+
+    expect(callSlackApiMock).toHaveBeenCalledWith("agents.sessions.setStatus", {
+      channel_id: "D123",
+      status: "processing",
+    });
   });
 
-  test("falls back to the reaction path when status API delivery fails", async () => {
+  test("falls back to adding a reaction when the status call fails", async () => {
     callSlackApiMock
       .mockImplementationOnce(async () => {
         throw new Error("missing_scope");
       })
       .mockImplementationOnce(async () => ({ ok: true }));
 
-    await sendSlackAssistantThreadStatus(
-      "C123",
-      "1700000000.000100",
-      "is working...",
-      ["Reading files"],
-    );
+    await sendSlackAgentSessionStatus({
+      channel: "C123",
+      phase: "thinking",
+      threadTs,
+    });
 
     expect(callSlackApiMock).toHaveBeenCalledTimes(2);
     expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "reactions.add", {
       channel: "C123",
       name: "eyes",
-      timestamp: "1700000000.000100",
+      timestamp: threadTs,
     });
   });
+
+  test("falls back to removing the reaction once the turn is no longer running", async () => {
+    callSlackApiMock
+      .mockImplementationOnce(async () => {
+        throw new Error("missing_scope");
+      })
+      .mockImplementationOnce(async () => ({ ok: true }));
+
+    await sendSlackAgentSessionStatus({
+      channel: "C123",
+      phase: "idle",
+      threadTs,
+    });
+
+    expect(callSlackApiMock).toHaveBeenNthCalledWith(2, "reactions.remove", {
+      channel: "C123",
+      name: "eyes",
+      timestamp: threadTs,
+    });
+  });
+
+  test("stays quiet when the status fails and there is nothing to react to", async () => {
+    callSlackApiMock.mockImplementationOnce(async () => {
+      throw new Error("missing_scope");
+    });
+
+    await sendSlackAgentSessionStatus({ channel: "D123", phase: "thinking" });
+
+    expect(callSlackApiMock).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe("updateSlackMessage", () => {

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

@@ -2,17 +2,18 @@
  * Slack outbound message orchestration.
  *
  * Handles text + Block Kit delivery, message updates, approval prompts,
- * typing indicators, reactions, thread status, ephemeral messages, and
- * attachments by calling the Slack Web API directly via ./api.ts.
+ * agent session status, reactions, ephemeral messages, and attachments by
+ * calling the Slack Web API directly via ./api.ts.
  */
 
 import type { Button, KnownBlock } from "@slack/types";
 import type {
   ApprovalUIMetadata,
   MessageAudience,
-  SlackStreamOp,
+  StreamOp,
 } from "@vellumai/gateway-client";
 
+import type { AssistantActivityPhase } from "../../../api/index.js";
 import { getAttachmentContent } from "../../../persistence/attachments-store.js";
 import type { RuntimeAttachmentMetadata } from "../../../runtime/http-types.js";
 import { getLogger } from "../../../util/logger.js";
@@ -26,6 +27,7 @@ import {
   uploadToSlackUrl,
 } from "./api.js";
 import { renderSlackBlocks } from "./render.js";
+import { toSlackStreamTasks } from "./stream-tasks.js";
 import { SlackApiError } from "./web-api-transport.js";
 
 const log = getLogger("slack-send");
@@ -209,11 +211,6 @@ function buildApprovalFallbackText(
   return text.includes(instructions) ? text : `${text}\n\n${instructions}`;
 }
 
-/**
- * Post a Slack text message with optional Block Kit formatting.
- *
- * Always posts. Replacing an existing message is {@link updateSlackMessage}.
- */
 /**
  * Replace a Slack message in place via `chat.update`.
  *
@@ -244,6 +241,11 @@ export async function updateSlackMessage(
   return result;
 }
 
+/**
+ * Post a Slack text message with optional Block Kit formatting.
+ *
+ * Always posts. Replacing an existing message is {@link updateSlackMessage}.
+ */
 export async function sendSlackReply(
   chatId: string,
   text: string,
@@ -296,28 +298,47 @@ export async function sendSlackReply(
 }
 
 /**
- * Execute one Slack streaming operation against a channel, returning the
- * stream `ts` so the caller can carry it across `append`/`stop` calls. `start`
+ * Execute one growing-reply operation against a Slack channel, returning the
+ * stream `ts` so the caller can carry it across `append` and `stop`. `start`
  * mints a new `ts`; `append` and `stop` echo the one they were given.
  *
+ * Slack's stream *is* the reply, so `stop` finalizes the message already on
+ * screen. That is why the appended delta is what goes on the wire here while
+ * the op's complete `text` is used only to hoist any images out of the
+ * finished reply: Slack has been shown every word already.
+ *
  * 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 sendSlackStreamOp(
   channel: string,
-  op: SlackStreamOp,
+  op: StreamOp,
 ): Promise<SlackSendResult> {
+  const tasks = op.plan ? toSlackStreamTasks(op.plan.steps) : undefined;
+  const planTitle = op.plan?.title;
+
   switch (op.action) {
     case "start": {
+      if (!op.anchorMessageId) {
+        // Slack streams into a thread and rejects a start without one. Saying
+        // so is the honest answer: an empty thread id would be refused by the
+        // API anyway, and the caller falls back to sending the reply whole.
+        log.warn({ channel }, "Slack stream start has no thread to open on");
+        return { ok: false };
+      }
       const ts = await startSlackStream({
         channel,
-        threadTs: op.threadTs,
-        markdownText: op.markdownText,
-        taskDisplayMode: op.taskDisplayMode,
-        planTitle: op.planTitle,
-        tasks: op.tasks,
-        recipientUserId: op.recipientUserId,
-        recipientTeamId: op.recipientTeamId,
+        threadTs: op.anchorMessageId,
+        markdownText: op.appended ?? op.text,
+        // Fixed for the stream's lifetime at start, while a plan usually
+        // arrives after the first text flush has opened it. It only affects
+        // how task chunks render, so a stream that never carries a plan still
+        // reads as a plain message.
+        taskDisplayMode: "plan",
+        planTitle,
+        tasks,
+        recipientUserId: op.audience?.userId,
+        recipientTeamId: op.audience?.userOrgId,
       });
       log.info({ channel, ts }, "Slack stream started");
       return { ok: ts !== undefined, ts };
@@ -325,28 +346,40 @@ export async function sendSlackStreamOp(
     case "append": {
       await appendSlackStream({
         channel,
-        streamTs: op.streamTs,
-        markdownText: op.markdownText,
-        planTitle: op.planTitle,
-        tasks: op.tasks,
+        streamTs: op.streamId,
+        markdownText: op.appended,
+        planTitle,
+        tasks,
       });
-      return { ok: true, ts: op.streamTs };
+      return { ok: true, ts: op.streamId };
     }
     case "stop": {
       await stopSlackStream({
         channel,
-        streamTs: op.streamTs,
-        markdownText: op.markdownText,
-        blocks: op.blocks,
-        planTitle: op.planTitle,
-        tasks: op.tasks,
+        streamTs: op.streamId,
+        markdownText: op.appended,
+        // Images referenced in the reply do not render inside the streamed
+        // markdown, so they are hoisted into blocks below it. Derived here
+        // from the whole reply rather than handed down, because which parts of
+        // a message become blocks is Slack's rendering decision.
+        blocks: op.text ? imageBlocksFor(op.text) : undefined,
+        planTitle,
+        tasks,
       });
-      log.info({ channel, ts: op.streamTs }, "Slack stream stopped");
-      return { ok: true, ts: op.streamTs };
+      log.info({ channel, ts: op.streamId }, "Slack stream stopped");
+      return { ok: true, ts: op.streamId };
     }
   }
 }
 
+/** Image blocks for a finished reply, or nothing when it references none. */
+function imageBlocksFor(text: string): KnownBlock[] | undefined {
+  const blocks = renderSlackBlocks(text)?.filter(
+    (block) => block.type === "image",
+  );
+  return blocks && blocks.length > 0 ? blocks : undefined;
+}
+
 /**
  * Add or remove an emoji reaction on a Slack message.
  * Non-throwing: logs errors but returns silently.
@@ -376,37 +409,73 @@ export async function sendSlackReaction(
   }
 }
 
+/** How Slack spells each activity phase on an agent session. */
+const SLACK_SESSION_STATUS: Record<
+  AssistantActivityPhase,
+  "active" | "processing" | "suspended"
+> = {
+  idle: "active",
+  thinking: "processing",
+  streaming: "processing",
+  tool_running: "processing",
+  // Slack's own word for a session waiting on a person, which is what an
+  // approval is. It suppresses the stop button, which would otherwise offer to
+  // cancel a turn that is not running.
+  awaiting_confirmation: "suspended",
+};
+
 /**
- * Set or clear the Slack Assistants API thread status indicator.
- * Falls back to emoji reactions for installs without `assistant:write` scope.
+ * Set the status of the Slack agent session for a thread.
+ *
+ * `active` is a real transition rather than a clear: the loading UX stays up
+ * for an hour if a turn ends without one, so every caller that sets a busy
+ * phase owes an `idle`.
+ *
+ * `initiator_user_id` is read only when Slack creates the session, so it is
+ * passed on every call and Slack ignores it after the first.
+ *
+ * Falls back to an emoji reaction on failure, which is all a workspace that
+ * denies the scope can show. Reports whether the session status itself landed,
+ * because a caller that owes a terminal transition has to know it was lost: the
+ * reaction cannot clear a status the API already set.
  */
-export async function sendSlackAssistantThreadStatus(
-  channel: string,
-  threadTs: string,
-  status: string,
-  loadingMessages?: readonly string[],
-): Promise<void> {
+export async function sendSlackAgentSessionStatus(params: {
+  channel: string;
+  phase: AssistantActivityPhase;
+  /** Thread root, absent in a DM the app has not threaded. */
+  threadTs?: string;
+  /** The message that opened the turn, used only by the reaction fallback. */
+  messageTs?: string;
+  initiatorUserId?: string;
+}): Promise<boolean> {
+  const { channel, phase, threadTs, messageTs, initiatorUserId } = params;
+  const status = SLACK_SESSION_STATUS[phase];
   try {
-    const body: Record<string, unknown> = {
+    await callSlackApi("agents.sessions.setStatus", {
       channel_id: channel,
-      thread_ts: threadTs,
       status,
-    };
-    if (loadingMessages !== undefined) {
-      body.loading_messages = loadingMessages;
-    }
-
-    await callSlackApi("assistant.threads.setStatus", body);
-    return;
+      ...(threadTs ? { thread_ts: threadTs } : {}),
+      ...(initiatorUserId ? { initiator_user_id: initiatorUserId } : {}),
+    });
+    return true;
   } catch {
     log.warn(
-      { channel },
-      "Slack assistant.threads.setStatus failed, falling back to reaction",
+      { channel, status },
+      "Slack agents.sessions.setStatus failed, falling back to reaction",
     );
   }
 
-  const isSet = status.length > 0;
-  await sendSlackReaction(channel, "eyes", threadTs, isSet ? "add" : "remove");
+  const reactionTarget = threadTs ?? messageTs;
+  if (!reactionTarget) {
+    return false;
+  }
+  await sendSlackReaction(
+    channel,
+    "eyes",
+    reactionTarget,
+    status === "processing" ? "add" : "remove",
+  );
+  return false;
 }
 
 export type SlackAttachmentResult = {

package/src/messaging/providers/slack/stream-tasks.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import { toSlackStreamTasks } from "./stream-tasks.js";
+
+describe("toSlackStreamTasks", () => {
+  test("maps steps onto Slack task cards with stable ids and details", () => {
+    expect(
+      toSlackStreamTasks([
+        {
+          label: "Check weather",
+          status: "completed",
+          detail: "Forecast fetched",
+        },
+        { label: "Summarize", status: "failed" },
+      ]),
+    ).toEqual([
+      {
+        id: "task-0",
+        title: "Check weather",
+        status: "complete",
+        details: "Forecast fetched",
+      },
+      { id: "task-1", title: "Summarize", status: "error" },
+    ]);
+  });
+});

package/src/messaging/providers/slack/stream-tasks.ts

@@ -0,0 +1,39 @@
+/**
+ * Slack's task-card vocabulary for a plan carried on a growing reply.
+ *
+ * Lives channel-side because both halves are Slack's: the `task_update` chunk
+ * shape, and a status vocabulary that spells two of the assistant's four
+ * statuses differently. The core sends the plan; what it becomes is here.
+ */
+
+import type { SlackStreamTask, StreamPlanStep } from "@vellumai/gateway-client";
+
+const TASK_PROGRESS_STATUS_TO_SLACK: Record<
+  StreamPlanStep["status"],
+  SlackStreamTask["status"]
+> = {
+  pending: "pending",
+  in_progress: "in_progress",
+  completed: "complete",
+  failed: "error",
+};
+
+/**
+ * Map ordered `task_progress` steps onto Slack streaming task cards. Step
+ * position supplies the stable card `id` (a step keeps its index across
+ * updates), the label becomes the card title, the step detail becomes the
+ * card details, and the surface status maps onto Slack's task-card status
+ * vocabulary.
+ *
+ * @see https://docs.slack.dev/ai/developing-agents
+ */
+export function toSlackStreamTasks(
+  steps: readonly StreamPlanStep[],
+): SlackStreamTask[] {
+  return steps.map((step, index) => ({
+    id: `task-${index}`,
+    title: step.label,
+    status: TASK_PROGRESS_STATUS_TO_SLACK[step.status],
+    ...(step.detail ? { details: step.detail } : {}),
+  }));
+}

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

@@ -1,11 +1,11 @@
+import type { KnownBlock } from "@slack/types";
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { getLogger } from "../../../util/logger.js";
 import type { ChannelTransport } from "../channel-transport.js";
 import {
-  sendSlackAssistantThreadStatus,
+  sendSlackAgentSessionStatus,
   sendSlackAttachments,
-  sendSlackReaction,
   sendSlackReply,
   sendSlackStreamOp,
   updateSlackMessage,
@@ -13,6 +13,11 @@ import {
 
 const log = getLogger("slack-transport");
 
+/** Slack's rendering of a settled message. */
+function mutedBlocks(text: string): KnownBlock[] {
+  return [{ type: "context", elements: [{ type: "mrkdwn", text }] }];
+}
+
 export const slackTransport: ChannelTransport = {
   channel: "slack",
 
@@ -25,7 +30,7 @@ export const slackTransport: ChannelTransport = {
       const result = await sendSlackReply(chatId, text, {
         threadTs,
         approval: payload.approval,
-        useBlocks: payload.useBlocks,
+        useBlocks: payload.renderRichly,
         audience: payload.audience,
       });
       sentTs = result.ts;
@@ -57,29 +62,26 @@ export const slackTransport: ChannelTransport = {
       target.chatId,
       target.messageId,
       target.text,
-      { blocks: target.blocks, useBlocks: target.useBlocks },
+      {
+        // Slack's answer to a settled message is a context block, which reads
+        // smaller and greyer than body text.
+        blocks:
+          target.emphasis === "muted" ? mutedBlocks(target.text) : undefined,
+        useBlocks: target.renderRichly,
+      },
     );
     return { ok: true, ts: result.ts };
   },
 
-  async react(_ctx, target) {
-    await sendSlackReaction(
-      target.chatId,
-      target.emoji,
-      target.messageId,
-      target.action,
-    );
-    return { ok: true };
-  },
-
-  async setThreadStatus(_ctx, status) {
-    await sendSlackAssistantThreadStatus(
-      status.chatId,
-      status.threadTs,
-      status.status,
-      status.loadingMessages,
-    );
-    return { ok: true };
+  async setActivity(ctx, target) {
+    const ok = await sendSlackAgentSessionStatus({
+      channel: target.chatId,
+      phase: target.phase,
+      threadTs: ctx.params.threadTs,
+      messageTs: ctx.params.messageTs,
+      initiatorUserId: target.initiatorUserId,
+    });
+    return { ok };
   },
 
   async streamReply(_ctx, chatId, op) {