@vellumai/assistant 0.11.8 → 0.11.9-staging.2

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

@@ -1,8 +1,10 @@
 import type { KnownBlock } from "@slack/types";
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
+import { extractThreadTsFromCallbackUrl } from "../../../channels/slack-callback-url.js";
 import { getLogger } from "../../../util/logger.js";
 import type { ChannelTransport } from "../channel-transport.js";
+import { SLACK_STREAM_MARKDOWN_LIMIT } from "./api.js";
 import {
   sendSlackAgentSessionStatus,
   sendSlackAttachments,
@@ -94,7 +96,31 @@ export const slackTransport: ChannelTransport = {
     return { ok };
   },
 
-  async streamReply(_ctx, chatId, op) {
-    return sendSlackStreamOp(chatId, op);
+  // `chat.startStream` and `chat.appendStream` both cap `markdown_text`, so
+  // the caller splits a wider delta and advances its delivered mark once per
+  // operation this transport confirms.
+  maxStreamTextChars: SLACK_STREAM_MARKDOWN_LIMIT,
+
+  // `chat.stopStream` finalizes the streamed message in place, so what the
+  // stream leaves behind IS the reply and durable delivery must not resend it.
+  streamPersists: true,
+
+  /**
+   * `chat.startStream` streams into a thread, so a turn with no thread to
+   * open under cannot stream. Resolving that here, from this channel's own
+   * callback, is what keeps Slack's addressing out of the shared session:
+   * a start with no thread reports not-ok and the caller sends the finished
+   * reply instead.
+   */
+  async streamReply(ctx, chatId, op) {
+    if (op.action !== "start") {
+      return sendSlackStreamOp(chatId, op);
+    }
+    const threadTs =
+      op.anchorMessageId ?? extractThreadTsFromCallbackUrl(ctx.callbackUrl);
+    if (!threadTs) {
+      return { ok: false };
+    }
+    return sendSlackStreamOp(chatId, { ...op, anchorMessageId: threadTs });
   },
 };

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

@@ -35,6 +35,7 @@ const {
   sendTelegramReaction,
   sendTelegramReply,
   sendTelegramRichReply,
+  TELEGRAM_DRAFT_TEXT_LIMIT,
 } = await import("./send.js");
 const { telegramTransport } = await import("./transport.js");
 
@@ -444,3 +445,161 @@ describe("editTelegramMessage", () => {
     expect(sendMessageCalls()).toHaveLength(0);
   });
 });
+
+describe("telegramTransport.streamReply", () => {
+  const ctx: CallbackContext = {
+    callbackUrl: "https://example.test/deliver/telegram?chatId=123",
+    params: {},
+  };
+
+  test("opens a draft carrying the whole partial reply", async () => {
+    const result = await telegramTransport.streamReply?.(ctx, "123", {
+      action: "start",
+      text: "Looking that up",
+      appended: "Looking that up",
+    });
+
+    const calls = callsTo("sendMessageDraft");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]![1]).toMatchObject({
+      chat_id: 123,
+      text: "Looking that up",
+    });
+    // The id is minted here, not handed back by Telegram, and must be usable
+    // as the stream id the later append addresses.
+    expect(Number(result?.ts)).toBeGreaterThan(0);
+    expect(result?.ok).toBe(true);
+  });
+
+  test("advances one draft by resending the whole text under the same id", async () => {
+    await telegramTransport.streamReply?.(ctx, "123", {
+      action: "append",
+      streamId: "4242",
+      text: "Looking that up. Found it.",
+      appended: ". Found it.",
+    });
+
+    const calls = callsTo("sendMessageDraft");
+    expect(calls).toHaveLength(1);
+    // Telegram animates between drafts sharing an id, so the call carries the
+    // whole reply so far rather than the delta.
+    expect(calls[0]![1]).toMatchObject({
+      chat_id: 123,
+      draft_id: 4242,
+      text: "Looking that up. Found it.",
+    });
+  });
+
+  test("draws a plan into the draft, since Telegram has no task primitive", async () => {
+    await telegramTransport.streamReply?.(ctx, "123", {
+      action: "append",
+      streamId: "4242",
+      text: "Working.",
+      plan: {
+        title: "Answering",
+        steps: [
+          { label: "Search docs", status: "completed" },
+          { label: "Summarize", status: "in_progress" },
+          { label: "Reply", status: "pending" },
+        ],
+      },
+    });
+
+    const body = callsTo("sendMessageDraft")[0]![1] as { text: string };
+    expect(body.text).toBe(
+      "Working.\n\nAnswering\n✓ Search docs\n▸ Summarize\n· Reply",
+    );
+  });
+
+  test("stopping does nothing, because sending the reply clears the draft", async () => {
+    const result = await telegramTransport.streamReply?.(ctx, "123", {
+      action: "stop",
+      streamId: "4242",
+      text: "All done.",
+    });
+
+    expect(callsTo("sendMessageDraft")).toHaveLength(0);
+    expect(result).toEqual({ ok: true, ts: "4242" });
+  });
+
+  test("sends the chat id as the integer the draft method requires", async () => {
+    // `sendMessageDraft` takes an Integer chat_id, not the "Integer or String"
+    // most methods accept, so the string the transport carries has to become a
+    // number on the wire.
+    await telegramTransport.streamReply?.(ctx, "123", {
+      action: "start",
+      text: "Hi",
+      appended: "Hi",
+    });
+
+    const body = callsTo("sendMessageDraft")[0]![1] as { chat_id: unknown };
+    expect(body.chat_id).toBe(123);
+  });
+
+  test("refuses a chat id that cannot be an integer, without calling out", async () => {
+    const result = await telegramTransport.streamReply?.(ctx, "@somechannel", {
+      action: "start",
+      text: "Hi",
+      appended: "Hi",
+    });
+
+    expect(callsTo("sendMessageDraft")).toHaveLength(0);
+    expect(result).toEqual({ ok: false });
+  });
+
+  test("a draft past the cap keeps its live tail, not a frozen prefix", async () => {
+    // Telegram caps a draft at 4096. Keeping the head would freeze the preview
+    // the moment the reply passed the cap, and would cut off anything drawn
+    // beneath it; the tail is the part still moving.
+    const body = "HEADMARK" + "a".repeat(5_000);
+    await telegramTransport.streamReply?.(ctx, "123", {
+      action: "append",
+      streamId: "4242",
+      text: body + "TAILMARK",
+      appended: "TAILMARK",
+      plan: { steps: [{ label: "Summarize", status: "in_progress" }] },
+    });
+
+    const sent = (callsTo("sendMessageDraft")[0]![1] as { text: string }).text;
+    expect(sent.length).toBe(TELEGRAM_DRAFT_TEXT_LIMIT);
+    // The newest text and the plan beneath it survive; the stale head is what
+    // gets dropped, which is the opposite of a frozen prefix.
+    expect(sent).toContain("TAILMARK");
+    expect(sent).toContain("Summarize");
+    expect(sent).not.toContain("HEADMARK");
+  });
+
+  test("a trimmed draft never begins with half of a character", async () => {
+    // The cap counts UTF-16 code units, so a tail cut can land between the
+    // halves of an emoji and send a lone surrogate.
+    const emoji = "\u{1F600}";
+    const body = emoji.repeat(3_000);
+    await telegramTransport.streamReply?.(ctx, "123", {
+      action: "append",
+      streamId: "4242",
+      text: body,
+      appended: emoji,
+    });
+
+    const sent = (callsTo("sendMessageDraft")[0]![1] as { text: string }).text;
+    const first = sent.charCodeAt(0);
+    expect(first >= 0xdc00 && first <= 0xdfff).toBe(false);
+    expect(sent.length).toBeLessThanOrEqual(TELEGRAM_DRAFT_TEXT_LIMIT);
+  });
+
+  test("a refused draft reports not-ok so the caller falls back", async () => {
+    // Telegram offers drafts in private chats only; anywhere else the call is
+    // rejected, and that rejection is the whole of the per-conversation rule.
+    callTelegramBotApiMock.mockImplementation(async () => {
+      throw new Error("Bad Request: chat type is not supported");
+    });
+
+    const result = await telegramTransport.streamReply?.(ctx, "123", {
+      action: "start",
+      text: "Looking that up",
+      appended: "Looking that up",
+    });
+
+    expect(result).toEqual({ ok: false });
+  });
+});

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

@@ -444,3 +444,96 @@ export async function sendTelegramTypingIndicator(
     return false;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Live message drafts (sendMessageDraft)
+// ---------------------------------------------------------------------------
+
+/**
+ * Telegram caps a message, and so a draft's text, at 4096 characters.
+ *
+ * A draft is a preview rather than the reply, so an over-long partial keeps
+ * its tail rather than being split across drafts: splitting would animate the
+ * reader back to the start of the reply every time it grew past the cap. The
+ * tail is also the live end of the draft, so a reply past the cap keeps
+ * moving instead of freezing on a prefix, and anything drawn beneath it
+ * stays visible.
+ */
+export const TELEGRAM_DRAFT_TEXT_LIMIT = 4096;
+
+/**
+ * The tail of a draft that Telegram will accept, cut on a character boundary.
+ *
+ * The cap counts UTF-16 code units, so slicing to it can land between the two
+ * halves of an astral character (an emoji, which a plan's status glyphs and a
+ * reply's own text both carry) and send a lone surrogate. Dropping a leading
+ * low surrogate costs one character and keeps the text well-formed.
+ */
+function draftTail(text: string): string {
+  if (text.length <= TELEGRAM_DRAFT_TEXT_LIMIT) {
+    return text;
+  }
+  const tail = text.slice(-TELEGRAM_DRAFT_TEXT_LIMIT);
+  const first = tail.charCodeAt(0);
+  return first >= 0xdc00 && first <= 0xdfff ? tail.slice(1) : tail;
+}
+
+/**
+ * How long a draft survives without being re-sent: Telegram describes it as
+ * "a temporary 30-second preview". A draft that stops being advanced
+ * disappears rather than lingering with stale text.
+ */
+export const TELEGRAM_DRAFT_TTL_MS = 30_000;
+
+/**
+ * Show, or advance, the live draft of a reply still being written.
+ *
+ * `sendMessageDraft` takes the whole partial reply rather than a delta and
+ * lets Telegram's clients animate the difference, which is why every call
+ * passes the full text. Reusing one `draft_id` is what makes those calls read
+ * as one growing draft: a different id replaces the draft without animation.
+ * Empty text is meaningful, rendering Telegram's own "Thinking..." placeholder,
+ * so it is passed through rather than skipped.
+ *
+ * The draft is a preview and never the reply. Telegram's own words: "once the
+ * output is finalized, you must call sendMessage with the complete message to
+ * persist it". It also clears the moment the bot sends a real message, so
+ * nothing has to clear it, and it survives only {@link TELEGRAM_DRAFT_TTL_MS}
+ * without being re-sent.
+ *
+ * Private chats only, and `chat_id` here is an Integer rather than the
+ * "Integer or String" most methods accept, so a non-numeric chat id cannot
+ * address a draft at all and is refused rather than sent to be rejected.
+ *
+ * @see https://core.telegram.org/bots/api#sendmessagedraft
+ */
+export async function sendTelegramMessageDraft(
+  chatId: string,
+  draftId: number,
+  text: string,
+  opts?: TelegramSendOptions,
+): Promise<boolean> {
+  const numericChatId = Number(chatId);
+  if (!Number.isSafeInteger(numericChatId)) {
+    log.debug(
+      { chatId, draftId },
+      "Telegram drafts address a chat by integer id; skipping draft",
+    );
+    return false;
+  }
+  try {
+    await callTelegramBotApi("sendMessageDraft", {
+      chat_id: numericChatId,
+      draft_id: draftId,
+      text: draftTail(text),
+      ...threadIdPayloadFields(opts),
+    });
+    return true;
+  } catch (err) {
+    log.debug(
+      { err, chatId, draftId },
+      "Failed to send Telegram message draft",
+    );
+    return false;
+  }
+}

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

@@ -1,3 +1,4 @@
+import type { StreamPlan, StreamPlanStep } from "@vellumai/gateway-client";
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { getLogger } from "../../../util/logger.js";
@@ -10,6 +11,7 @@ import type { TelegramSendOptions } from "./send.js";
 import {
   editTelegramMessage,
   sendTelegramAttachments,
+  sendTelegramMessageDraft,
   sendTelegramReaction,
   sendTelegramReply,
   sendTelegramRichReply,
@@ -27,12 +29,50 @@ function threadOptions(ctx: CallbackContext): TelegramSendOptions | undefined {
   return threadId ? { messageThreadId: threadId } : undefined;
 }
 
+/**
+ * A plan drawn into the draft's own text, because Telegram has no task
+ * primitive a bot may use: `sendChecklist` is business-account only. Rendering
+ * it here rather than above the seam is the point of the seam. The glyphs
+ * carry the status without a legend, and a step keeps its place as it
+ * advances so the reader watches one list move rather than a new one appear.
+ */
+function renderPlanAsText(plan: StreamPlan): string {
+  const glyph: Record<StreamPlanStep["status"], string> = {
+    completed: "\u2713",
+    in_progress: "\u25b8",
+    pending: "\u00b7",
+    failed: "\u2717",
+  };
+  const lines = plan.steps.map((step) => `${glyph[step.status]} ${step.label}`);
+  return [plan.title, ...lines].filter(Boolean).join("\n");
+}
+
+/** The draft's whole text: the reply so far, with any plan beneath it. */
+function draftText(text: string, plan: StreamPlan | undefined): string {
+  const body = text.trim();
+  const planText = plan ? renderPlanAsText(plan) : "";
+  return [body, planText].filter(Boolean).join("\n\n");
+}
+
+/**
+ * Telegram's draft id is minted by the caller, unlike a stream id a platform
+ * hands back, and only has to be non-zero and stable for the life of one
+ * draft. The clock supplies that without any state to keep between calls.
+ */
+function mintDraftId(): number {
+  return Date.now();
+}
+
 export const telegramTransport: ChannelTransport = {
   channel: "telegram",
 
   // Telegram clears a chat action after about five seconds.
   activityRefreshMs: 4_000,
 
+  // The draft is a preview: it expires on its own, and the moment the bot
+  // sends the real message, so the reply is still owed after the stream ends.
+  streamPersists: false,
+
   async react(target) {
     return sendTelegramReaction(
       target.chatId,
@@ -86,6 +126,37 @@ export const telegramTransport: ChannelTransport = {
     return { ok: true };
   },
 
+  /**
+   * Show the reply as it is written, in Telegram's own live draft.
+   *
+   * Every call carries the whole partial reply rather than a delta: Telegram
+   * animates the difference between drafts sharing a `draft_id`, so sending
+   * only what is new would replace the draft with the fragment. `stop` has
+   * nothing to do, since the draft clears itself when the real reply sends.
+   *
+   * A start that Telegram refuses (a chat that is not private, where drafts
+   * are not offered) reports not-ok, and the caller falls back to sending the
+   * finished reply. That is the whole of the per-conversation rule: it is
+   * answered here, where the platform's constraint lives.
+   */
+  async streamReply(ctx, chatId, op) {
+    const opts = threadOptions(ctx);
+    if (op.action === "stop") {
+      return { ok: true, ts: op.streamId };
+    }
+    const draftId = op.action === "start" ? mintDraftId() : Number(op.streamId);
+    if (!Number.isFinite(draftId) || draftId === 0) {
+      return { ok: false };
+    }
+    const sent = await sendTelegramMessageDraft(
+      chatId,
+      draftId,
+      draftText(op.text, op.plan),
+      opts,
+    );
+    return sent ? { ok: true, ts: String(draftId) } : { ok: false };
+  },
+
   async setActivity(ctx, target) {
     // Telegram's chat action expires by itself after a few seconds, so a phase
     // that is not running needs no clearing call.

package/src/messaging/reaction-envelopes.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+
+import { writeSlackMetadata } from "./providers/slack/message-metadata.js";
+import {
+  buildNeutralReactionMeta,
+  buildSlackReactionMeta,
+  type ReactionEnvelopeFacts,
+} from "./reaction-envelopes.js";
+import { readProviderMetadata } from "./read-provider-metadata.js";
+
+const typedFacts: ReactionEnvelopeFacts = {
+  channel: "slack",
+  chatId: "C1",
+  targetMessageId: "1700000000.000100",
+  emoji: "blob_wave",
+  emojiKind: "shortcode",
+  emojiName: "blob_wave",
+  op: "added",
+  actorExternalId: "U1",
+  actorDisplayName: "Alice",
+};
+
+describe("a reaction's typed emoji survives the stored envelope", () => {
+  test("the Slack envelope writes the fields and reads them back", () => {
+    const read = readProviderMetadata(
+      JSON.stringify({
+        slackMeta: writeSlackMetadata(buildSlackReactionMeta(typedFacts)),
+      }),
+    );
+
+    expect(read?.reaction).toMatchObject({
+      emoji: "blob_wave",
+      emojiKind: "shortcode",
+      emojiName: "blob_wave",
+      op: "added",
+      targetMessageId: "1700000000.000100",
+    });
+  });
+
+  test("the neutral envelope writes the fields and reads them back", () => {
+    const stored = buildNeutralReactionMeta({
+      ...typedFacts,
+      channel: "discord",
+      emoji: "<:party_blob:111>",
+      emojiKind: "custom",
+      emojiName: "party_blob",
+      emojiId: "111",
+      emojiAnimated: true,
+    });
+    const read = readProviderMetadata(
+      JSON.stringify({ providerMeta: JSON.stringify(stored) }),
+    );
+
+    expect(read?.reaction).toMatchObject({
+      emojiKind: "custom",
+      emojiName: "party_blob",
+      emojiId: "111",
+      emojiAnimated: true,
+    });
+  });
+
+  test("a Slack row carrying only the spelling still reads", () => {
+    const { emojiKind: _k, emojiName: _n, ...spellingOnly } = typedFacts;
+    const read = readProviderMetadata(
+      JSON.stringify({
+        slackMeta: writeSlackMetadata(buildSlackReactionMeta(spellingOnly)),
+      }),
+    );
+
+    expect(read?.reaction?.emoji).toBe("blob_wave");
+    expect(read?.reaction?.emojiKind).toBeUndefined();
+  });
+});

package/src/messaging/reaction-envelopes.ts

@@ -3,16 +3,27 @@
  * facts so the inbound intercept and the assistant's own reaction records
  * cannot drift apart.
  *
- * Slack keeps its own envelope because its transcript context builds
- * provider history from rows and reads only `slackMeta`; every other channel
- * writes the neutral shape `readProviderMetadata` serves to channel-agnostic
- * readers.
+ * The assistant's own reaction rows write the neutral shape on every channel,
+ * as every row the daemon authors does. Inbound Slack reaction rows still
+ * write Slack's own envelope, which `readProviderMetadata` maps on read; the
+ * Slack transcript reads the neutral envelope through its Slack view.
  */
+import {
+  pickReactionEmojiFields,
+  type ReactionEmojiFields,
+} from "@vellumai/service-contracts/reactions";
+
 import type { ChannelId } from "../channels/types.js";
 import type { ProviderMessageMetadata } from "./provider-message-metadata.js";
 import type { SlackMessageMetadata } from "./providers/slack/message-metadata.js";
+import { writeSlackMetadata } from "./providers/slack/message-metadata.js";
 
-export interface ReactionEnvelopeFacts {
+/**
+ * The emoji's typed identity is optional on the facts because the assistant's
+ * own reaction carries only the spelling it chose: it names an emoji rather
+ * than reporting one a channel described.
+ */
+export interface ReactionEnvelopeFacts extends ReactionEmojiFields {
   channel: ChannelId;
   /** Provider id of the chat the reaction belongs to. */
   chatId: string;
@@ -40,6 +51,7 @@ export function buildNeutralReactionMeta(
     reaction: {
       targetMessageId: facts.targetMessageId,
       emoji: facts.emoji,
+      ...pickReactionEmojiFields(facts),
       op: facts.op,
       ...(facts.actorDisplayName
         ? { actorDisplayName: facts.actorDisplayName }
@@ -48,6 +60,21 @@ export function buildNeutralReactionMeta(
   };
 }
 
+/**
+ * The serialized metadata key an inbound reaction row stores, chosen per
+ * channel: Slack rows write `slackMeta`, every other channel the neutral
+ * `providerMeta`. The one owner of that choice, so the two inbound writers
+ * (the intercept and the reaction-wake turn) cannot drift. The assistant's
+ * own reaction records write `buildNeutralReactionMeta` directly.
+ */
+export function buildReactionRowEnvelope(
+  facts: ReactionEnvelopeFacts,
+): { slackMeta: string } | { providerMeta: string } {
+  return facts.channel === "slack"
+    ? { slackMeta: writeSlackMetadata(buildSlackReactionMeta(facts)) }
+    : { providerMeta: JSON.stringify(buildNeutralReactionMeta(facts)) };
+}
+
 export function buildSlackReactionMeta(
   facts: ReactionEnvelopeFacts,
 ): SlackMessageMetadata {
@@ -69,6 +96,7 @@ export function buildSlackReactionMeta(
     ...(facts.actorDisplayName ? { displayName: facts.actorDisplayName } : {}),
     reaction: {
       emoji: facts.emoji,
+      ...pickReactionEmojiFields(facts),
       targetChannelTs: facts.targetMessageId,
       op: facts.op,
       ...(facts.actorDisplayName

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

@@ -20,9 +20,10 @@ import {
  * 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.
+ * `slackMeta` is Slack's own envelope, mapped on read. Inbound Slack rows
+ * still write it; the Slack-only fields it holds have no neutral equivalent
+ * and ride the neutral envelope's passthrough on the rows the daemon
+ * authors. 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.