@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/messaging/providers/slack/web-api-transport.ts

@@ -0,0 +1,367 @@
+/**
+ * Shared Slack Web API transport: the single implementation of request
+ * dispatch, rate-limit/5xx retries, envelope checking, and error
+ * classification used by both Slack feature surfaces (`api.ts` for
+ * streaming/uploads/channel info, `client.ts` for the typed messaging
+ * wrappers). Not to be confused with `transport.ts`, the outbound
+ * `ChannelTransport` delivery seam.
+ *
+ * There is exactly ONE `SlackApiError` class, defined here. Callers branch on
+ * three fields, all always present:
+ *   - `slackError`: Slack's error code (`"channel_not_found"`, ...), or
+ *     `"http_<status>"` for HTTP-level failures, or `"unknown_error"`.
+ *   - `category`: coarse classification for policy decisions
+ *     (`auth` / `rate_limit` / `permission` / ...).
+ *   - `status`: HTTP-shaped status for OAuth-refresh compatibility:
+ *     explicit HTTP status when the failure was HTTP-level, otherwise derived
+ *     from the category (`auth` → 401, `rate_limit` → 429, else 400).
+ *     `oauth/connection.js` retry logic and the adapter's user→bot fallback
+ *     key on `status === 401`.
+ */
+
+import type { OAuthConnection } from "../../../oauth/connection.js";
+import { getLogger } from "../../../util/logger.js";
+import type { SlackApiResponse } from "./types.js";
+
+const log = getLogger("slack-web-api");
+
+export const SLACK_API_BASE = "https://slack.com/api";
+const MAX_RATE_LIMIT_RETRIES = 3;
+const DEFAULT_RETRY_AFTER_S = 1;
+
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+
+export type SlackErrorCategory =
+  | "auth"
+  | "rate_limit"
+  | "not_found"
+  | "permission"
+  | "channel_not_found"
+  | "client_error"
+  | "transient"
+  | "unknown";
+
+const SLACK_ERROR_CODE_MAP: Record<string, SlackErrorCategory> = {
+  invalid_auth: "auth",
+  token_expired: "auth",
+  token_revoked: "auth",
+  not_authed: "auth",
+  account_inactive: "auth",
+  org_login_required: "auth",
+  rate_limited: "rate_limit",
+  ratelimited: "rate_limit",
+  channel_not_found: "channel_not_found",
+  is_archived: "channel_not_found",
+  not_in_channel: "permission",
+  missing_scope: "permission",
+  ekm_access_denied: "permission",
+  not_allowed_token_type: "permission",
+  restricted_action: "permission",
+  cannot_dm_bot: "permission",
+  user_not_found: "not_found",
+  message_not_found: "not_found",
+  thread_not_found: "not_found",
+  invalid_blocks: "client_error",
+};
+
+export function classifySlackError(
+  errorCode: string | undefined,
+): SlackErrorCategory {
+  if (!errorCode) {
+    return "unknown";
+  }
+  return SLACK_ERROR_CODE_MAP[errorCode] ?? "unknown";
+}
+
+function deriveStatus(category: SlackErrorCategory): number {
+  switch (category) {
+    case "auth":
+      return 401;
+    case "rate_limit":
+      return 429;
+    default:
+      return 400;
+  }
+}
+
+export class SlackApiError extends Error {
+  readonly slackError: string;
+  readonly category: SlackErrorCategory;
+  readonly status: number;
+
+  constructor(
+    slackError: string | undefined,
+    opts: { status?: number; message?: string } = {},
+  ) {
+    const code = slackError ?? "unknown_error";
+    super(opts.message ?? `Slack API error: ${code}`);
+    this.name = "SlackApiError";
+    this.slackError = code;
+    this.category = classifySlackError(slackError);
+    this.status = opts.status ?? deriveStatus(this.category);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Envelope checking
+// ---------------------------------------------------------------------------
+
+/**
+ * Check a Slack API response envelope and throw a classified `SlackApiError`
+ * when `ok` is false. Slack reports most failures as HTTP 200 with an error
+ * code in the body, so this runs on every successful HTTP exchange.
+ */
+export function checkSlackEnvelope<T extends SlackApiResponse>(data: T): T {
+  if (!data.ok) {
+    throw new SlackApiError(data.error);
+  }
+  return data;
+}
+
+function sleepMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function retryAfterSeconds(header: string | null): number {
+  return parseInt(header ?? "", 10) || DEFAULT_RETRY_AFTER_S;
+}
+
+// ---------------------------------------------------------------------------
+// Raw-token requests
+// ---------------------------------------------------------------------------
+
+export interface SlackRequestOptions {
+  /** Query parameters; presence selects GET (unless `body`/`form` is set). */
+  query?: Record<string, string | undefined>;
+  /** JSON body; presence selects POST with a JSON content type. */
+  body?: Record<string, unknown>;
+  /** Form body; presence selects POST with form encoding. */
+  form?: URLSearchParams;
+}
+
+function buildRequest(
+  token: string,
+  method: string,
+  opts: SlackRequestOptions,
+): { url: string; init: RequestInit } {
+  let url = `${SLACK_API_BASE}/${method}`;
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  };
+
+  if (opts.body) {
+    headers["Content-Type"] = "application/json; charset=utf-8";
+    return {
+      url,
+      init: { method: "POST", headers, body: JSON.stringify(opts.body) },
+    };
+  }
+  if (opts.form) {
+    headers["Content-Type"] = "application/x-www-form-urlencoded";
+    return { url, init: { method: "POST", headers, body: opts.form } };
+  }
+
+  const searchParams = new URLSearchParams();
+  for (const [k, v] of Object.entries(opts.query ?? {})) {
+    if (v !== undefined) {
+      searchParams.set(k, v);
+    }
+  }
+  const query = searchParams.toString();
+  if (query) {
+    url += `?${query}`;
+  }
+  return { url, init: { method: "GET", headers } };
+}
+
+/**
+ * Execute a raw-token Slack Web API request with the shared retry policy:
+ * HTTP 429 honors `Retry-After`, 5xx retries with fixed backoff, and
+ * body-level rate-limit errors (Slack sometimes returns HTTP 200 +
+ * `rate_limited`/`ratelimited`) retry via their classified category. All
+ * failures throw the unified `SlackApiError`.
+ */
+export async function rawSlackRequest<T extends SlackApiResponse>(
+  token: string,
+  method: string,
+  opts: SlackRequestOptions = {},
+): Promise<T> {
+  const { url, init } = buildRequest(token, method, opts);
+
+  for (let attempt = 0; attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {
+    const resp = await fetch(url, init);
+
+    if (resp.status === 429) {
+      if (attempt >= MAX_RATE_LIMIT_RETRIES) {
+        throw new SlackApiError("rate_limited", {
+          status: 429,
+          message: "Slack API rate limited",
+        });
+      }
+      const retryAfter = retryAfterSeconds(resp.headers.get("Retry-After"));
+      log.warn({ method, retryAfter, attempt }, "Slack rate limited, retrying");
+      await sleepMs(retryAfter * 1000);
+      continue;
+    }
+
+    if (resp.status >= 500) {
+      if (attempt >= MAX_RATE_LIMIT_RETRIES) {
+        throw new SlackApiError(`http_${resp.status}`, {
+          status: resp.status,
+          message: `Slack ${method} failed with status ${resp.status} after retries`,
+        });
+      }
+      log.warn(
+        { method, status: resp.status, attempt },
+        "Slack 5xx error, retrying",
+      );
+      await sleepMs(DEFAULT_RETRY_AFTER_S * 1000);
+      continue;
+    }
+
+    if (!resp.ok) {
+      throw new SlackApiError(`http_${resp.status}`, {
+        status: resp.status,
+        message: `Slack API HTTP ${resp.status}`,
+      });
+    }
+
+    const data = (await resp.json()) as T;
+
+    if (
+      !data.ok &&
+      classifySlackError(data.error) === "rate_limit" &&
+      attempt < MAX_RATE_LIMIT_RETRIES
+    ) {
+      log.warn(
+        { method, slackError: data.error, attempt },
+        "Slack rate limited (body), retrying",
+      );
+      await sleepMs(DEFAULT_RETRY_AFTER_S * 1000);
+      continue;
+    }
+
+    return checkSlackEnvelope(data);
+  }
+
+  // Unreachable: every loop exit path above either returns or throws.
+  throw new SlackApiError("rate_limited", {
+    status: 429,
+    message: "Slack API rate limited",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// OAuth-connection requests
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a Slack API request via a refreshing `OAuthConnection`.
+ *
+ * Slack returns HTTP 200 with `{ ok: false, error: "invalid_auth" }` for auth
+ * errors. Because `connection.request()` delegates to `withValidToken`, which
+ * only retries HTTP-level 401s, envelope auth errors (classified to
+ * `status === 401`) are caught here and retried once via
+ * `connection.withToken()`, which forces a token refresh first.
+ */
+async function connectionSlackRequest<T extends SlackApiResponse>(
+  connection: OAuthConnection,
+  method: string,
+  opts: SlackRequestOptions,
+): Promise<T> {
+  // `connection.request()` carries only query/body; silently dropping a form
+  // payload would send Slack a parameterless request that fails with a
+  // misleading Slack-side error. Fail fast instead: form-encoded methods are
+  // only reachable on Socket Mode installs, whose auth is a raw token.
+  if (opts.form) {
+    throw new SlackApiError("form_unsupported_over_oauth", {
+      message:
+        `Slack ${method} uses a form-encoded body, which is not supported ` +
+        "over a legacy OAuth connection; a Socket Mode bot token is required",
+    });
+  }
+
+  const query: Record<string, string> | undefined = opts.query
+    ? Object.fromEntries(
+        Object.entries(opts.query).filter(
+          (entry): entry is [string, string] => entry[1] !== undefined,
+        ),
+      )
+    : undefined;
+
+  for (let attempt = 0; attempt <= MAX_RATE_LIMIT_RETRIES; attempt++) {
+    const resp = await connection.request({
+      method: opts.body ? "POST" : "GET",
+      path: `/${method}`,
+      query: query && Object.keys(query).length > 0 ? query : undefined,
+      body: opts.body,
+    });
+
+    if (resp.status === 429) {
+      if (attempt >= MAX_RATE_LIMIT_RETRIES) {
+        throw new SlackApiError("rate_limited", {
+          status: 429,
+          message: "Slack API rate limited",
+        });
+      }
+      const retryAfter = retryAfterSeconds(
+        resp.headers["retry-after"] ?? resp.headers["Retry-After"] ?? null,
+      );
+      await sleepMs(retryAfter * 1000);
+      continue;
+    }
+
+    if (resp.status >= 400) {
+      throw new SlackApiError(`http_${resp.status}`, {
+        status: resp.status,
+        message: `Slack API HTTP ${resp.status}`,
+      });
+    }
+
+    const data = resp.body as T;
+
+    if (
+      !data.ok &&
+      classifySlackError(data.error) === "rate_limit" &&
+      attempt < MAX_RATE_LIMIT_RETRIES
+    ) {
+      await sleepMs(DEFAULT_RETRY_AFTER_S * 1000);
+      continue;
+    }
+
+    try {
+      return checkSlackEnvelope(data);
+    } catch (err) {
+      if (err instanceof SlackApiError && err.status === 401) {
+        return connection.withToken((freshToken) =>
+          rawSlackRequest<T>(freshToken, method, opts),
+        );
+      }
+      throw err;
+    }
+  }
+
+  // Unreachable: every loop exit path above either returns or throws.
+  throw new SlackApiError("rate_limited", {
+    status: 429,
+    message: "Slack API rate limited",
+  });
+}
+
+/**
+ * Dispatch a Slack Web API request on whichever auth form the caller holds:
+ * a raw token (Socket Mode installs) or a refreshing `OAuthConnection`
+ * (legacy OAuth installs).
+ */
+export async function slackRequest<T extends SlackApiResponse>(
+  auth: OAuthConnection | string,
+  method: string,
+  opts: SlackRequestOptions = {},
+): Promise<T> {
+  if (typeof auth === "string") {
+    return rawSlackRequest<T>(auth, method, opts);
+  }
+  return connectionSlackRequest<T>(auth, method, opts);
+}

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

@@ -17,7 +17,7 @@
 
 import {
   isParkAction,
-  PARK_STATUS_LABEL,
+  resolveDecisionStatusWord,
 } from "../../../runtime/channel-approval-types.js";
 import { getLogger } from "../../../util/logger.js";
 import { callSlackApi, getSlackMessageBlocks } from "./api.js";
@@ -46,13 +46,6 @@ const STATUS_GLYPH: Record<string, string> = {
   cancelled: ":no_entry_sign:",
 };
 
-const STATUS_WORD: Record<string, string> = {
-  approved: "Approved",
-  denied: "Denied",
-  expired: "Expired",
-  cancelled: "Cancelled",
-};
-
 /**
  * Glyph for a parked (leave-unverified) decision. A neutral "on hold" mark
  * rather than the `denied` red cross — the sender was neither trusted nor kept
@@ -69,9 +62,10 @@ export interface WithdrawSlackApprovalCardParams {
   status: string;
   /**
    * The action the guardian took, when known. A `denied` status reached by a
-   * park action (`leave_unverified`) reads as the neutral
-   * {@link PARK_STATUS_LABEL} rather than "Denied"; `block`/`reject` stay a
-   * denial. Omitted for status-only transitions (e.g. the expiry sweep).
+   * park action (`leave_unverified`) reads as the neutral park label (see
+   * {@link resolveDecisionStatusWord}) rather than "Denied"; `block`/`reject`
+   * stay a denial. Omitted for status-only transitions (e.g. the expiry
+   * sweep).
    */
   decidedAction?: string;
   /** Slack user id of the decider, when the decision came from Slack. */
@@ -87,9 +81,7 @@ export interface WithdrawSlackApprovalCardParams {
 function buildStatusText(params: WithdrawSlackApprovalCardParams): string {
   const park = params.status === "denied" && isParkAction(params.decidedAction);
   const glyph = park ? PARK_STATUS_GLYPH : (STATUS_GLYPH[params.status] ?? "");
-  const word = park
-    ? PARK_STATUS_LABEL
-    : (STATUS_WORD[params.status] ?? "Resolved");
+  const word = resolveDecisionStatusWord(params.status, params.decidedAction);
   let line = glyph ? `${glyph} *${word}*` : `*${word}*`;
   if (params.decidedByExternalUserId) {
     line += ` by <@${params.decidedByExternalUserId}>`;

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

@@ -30,7 +30,7 @@ mock.module("./api.js", () => ({
 }));
 
 const { TelegramNonRetryableError } = await import("./api.js");
-const { sendTelegramRichReply } = await import("./send.js");
+const { sendTelegramReply, sendTelegramRichReply } = await import("./send.js");
 const { telegramTransport } = await import("./transport.js");
 
 const approval: ApprovalUIMetadata = {
@@ -148,6 +148,36 @@ describe("sendTelegramRichReply", () => {
   });
 });
 
+describe("sendTelegramReply message id capture", () => {
+  test("returns the sent message id so approval cards can be addressed later", async () => {
+    callTelegramBotApiMock.mockImplementation(
+      async () => ({ message_id: 42 }) as never,
+    );
+
+    const result = await sendTelegramReply("123", "Please approve", approval);
+
+    expect(result.lastMessageId).toBe("42");
+  });
+
+  test("returns the id of the last chunk for a split message", async () => {
+    let nextId = 1;
+    callTelegramBotApiMock.mockImplementation(
+      async () => ({ message_id: nextId++ }) as never,
+    );
+
+    const result = await sendTelegramReply("123", "x".repeat(4500));
+
+    expect(callsTo("sendMessage")).toHaveLength(2);
+    expect(result.lastMessageId).toBe("2");
+  });
+
+  test("omits the message id when the API response lacks one", async () => {
+    const result = await sendTelegramReply("123", "Hello");
+
+    expect(result.lastMessageId).toBeUndefined();
+  });
+});
+
 describe("telegramTransport.deliver routing", () => {
   const ctx: CallbackContext = { callbackUrl: "/deliver/telegram", params: {} };
 

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

@@ -13,6 +13,7 @@ import { getLogger } from "../../../util/logger.js";
 import {
   callTelegramBotApi,
   callTelegramBotApiMultipart,
+  type TelegramMessage,
   TelegramNonRetryableError,
 } from "./api.js";
 import { renderTelegramHtml } from "./render.js";
@@ -121,6 +122,17 @@ function buildInlineKeyboard(approval: ApprovalUIMetadata): {
 // Public API
 // ---------------------------------------------------------------------------
 
+/** Outcome of a Telegram reply send. */
+export interface TelegramSendResult {
+  /**
+   * Channel-native id of the last sent chunk (the message carrying the
+   * inline keyboard when an approval was attached). Callers that need to
+   * address the message later (e.g. approval-card withdrawal) persist this.
+   * Undefined when the API response did not carry a message id.
+   */
+  lastMessageId?: string;
+}
+
 /**
  * Send a Telegram text reply, splitting long messages and optionally
  * attaching inline keyboard buttons for approval prompts.
@@ -130,9 +142,10 @@ export async function sendTelegramReply(
   text: string,
   approval?: ApprovalUIMetadata,
   opts?: TelegramSendOptions,
-): Promise<void> {
+): Promise<TelegramSendResult> {
   const chunks = splitText(text, TELEGRAM_MAX_MESSAGE_LEN);
 
+  let lastMessageId: string | undefined;
   for (let i = 0; i < chunks.length; i++) {
     const payload: Record<string, unknown> = {
       chat_id: chatId,
@@ -146,10 +159,18 @@ export async function sendTelegramReply(
       payload.reply_markup = buildInlineKeyboard(approval);
     }
 
-    await callTelegramBotApi("sendMessage", payload);
+    const sent = await callTelegramBotApi<TelegramMessage>(
+      "sendMessage",
+      payload,
+    );
+    lastMessageId =
+      typeof sent?.message_id === "number"
+        ? String(sent.message_id)
+        : undefined;
   }
 
   log.debug({ chatId, chunks: chunks.length }, "Telegram reply sent");
+  return lastMessageId !== undefined ? { lastMessageId } : {};
 }
 
 /**

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

@@ -0,0 +1,152 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Derive the mock signature from the real export so the test cannot drift from
+// the production call signature.
+type CallTelegramBotApi = typeof import("./api.js").callTelegramBotApi;
+
+const callTelegramBotApiMock = mock<CallTelegramBotApi>(
+  async () => ({}) as never,
+);
+
+mock.module("./api.js", () => ({
+  callTelegramBotApi: (method: string, body: Record<string, unknown>) =>
+    callTelegramBotApiMock(method, body),
+}));
+
+const { withdrawTelegramApprovalCard } = await import("./withdraw.js");
+
+const callsTo = (method: string) =>
+  callTelegramBotApiMock.mock.calls.filter((call) => call[0] === method);
+
+beforeEach(() => {
+  callTelegramBotApiMock.mockReset();
+  callTelegramBotApiMock.mockImplementation(async () => ({}) as never);
+});
+
+describe("withdrawTelegramApprovalCard", () => {
+  test("clears the inline keyboard and posts a silent quoted status reply", async () => {
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "42",
+      status: "approved",
+      postStatusReply: true,
+    });
+
+    const edits = callsTo("editMessageReplyMarkup");
+    expect(edits).toHaveLength(1);
+    expect(edits[0]?.[1]).toEqual({
+      chat_id: "chat-1",
+      message_id: 42,
+      reply_markup: null,
+    });
+
+    const sends = callsTo("sendMessage");
+    expect(sends).toHaveLength(1);
+    expect(sends[0]?.[1]).toEqual({
+      chat_id: "chat-1",
+      text: "✅ Approved",
+      reply_parameters: { message_id: 42, allow_sending_without_reply: true },
+      disable_notification: true,
+    });
+  });
+
+  test("skips the status reply when the decision originated on Telegram", async () => {
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "42",
+      status: "denied",
+      postStatusReply: false,
+    });
+
+    expect(callsTo("editMessageReplyMarkup")).toHaveLength(1);
+    expect(callsTo("sendMessage")).toHaveLength(0);
+  });
+
+  test("falls back to an empty inline keyboard when the null form is rejected", async () => {
+    callTelegramBotApiMock.mockImplementationOnce(async () => {
+      throw new Error("Bad Request: REPLY_MARKUP_INVALID");
+    });
+
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "7",
+      status: "expired",
+      postStatusReply: true,
+    });
+
+    const edits = callsTo("editMessageReplyMarkup");
+    expect(edits).toHaveLength(2);
+    expect(edits[1]?.[1]).toEqual({
+      chat_id: "chat-1",
+      message_id: 7,
+      reply_markup: { inline_keyboard: [] },
+    });
+    expect(callsTo("sendMessage")).toHaveLength(1);
+    expect(callsTo("sendMessage")[0]?.[1]).toMatchObject({
+      text: "⌛ Expired",
+    });
+  });
+
+  test("treats 'message is not modified' as already cleared", async () => {
+    callTelegramBotApiMock.mockImplementationOnce(async () => {
+      throw new Error("Bad Request: message is not modified");
+    });
+
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "7",
+      status: "approved",
+      postStatusReply: true,
+    });
+
+    // No empty-keyboard retry: the keyboard is already gone.
+    expect(callsTo("editMessageReplyMarkup")).toHaveLength(1);
+    expect(callsTo("sendMessage")).toHaveLength(1);
+  });
+
+  test("still posts the status reply when both keyboard edits fail", async () => {
+    callTelegramBotApiMock.mockImplementation(
+      async (method: string): Promise<never> => {
+        if (method === "editMessageReplyMarkup") {
+          throw new Error("Bad Request: message to edit not found");
+        }
+        return {} as never;
+      },
+    );
+
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "7",
+      status: "approved",
+      postStatusReply: true,
+    });
+
+    expect(callsTo("editMessageReplyMarkup")).toHaveLength(2);
+    expect(callsTo("sendMessage")).toHaveLength(1);
+  });
+
+  test("renders a parked denial with the neutral park label", async () => {
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "9",
+      status: "denied",
+      decidedAction: "leave_unverified",
+      postStatusReply: true,
+    });
+
+    expect(callsTo("sendMessage")[0]?.[1]).toMatchObject({
+      text: "⏸️ Left unverified",
+    });
+  });
+
+  test("skips everything on a non-numeric message id", async () => {
+    await withdrawTelegramApprovalCard({
+      chatId: "chat-1",
+      messageId: "not-a-number",
+      status: "approved",
+      postStatusReply: true,
+    });
+
+    expect(callTelegramBotApiMock.mock.calls).toHaveLength(0);
+  });
+});