@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/messaging/providers/slack/mention-source.ts

@@ -0,0 +1,287 @@
+/**
+ * Typed, validated representation of a Slack message's inline mention source:
+ * the verbatim mention markup plus the label snapshot resolved at ingress,
+ * with explicit workspace/install scope and a persist-time projectability
+ * fact.
+ *
+ * This module is pure and has no persistence or network callers. It defines
+ * the v1 contract (LUM-3023): consumers project readable text from persisted
+ * source data instead of trusting a one-shot ingress render. Projection is
+ * deterministic and snapshot-first; live lookups never participate at render
+ * time.
+ *
+ * Scope note: a Slack channel or user id is only meaningful within one
+ * workspace. `installTeamId` records the workspace the labels were resolved
+ * under when the ingress payload carries it; `null` means the deployment's
+ * single install implicitly defines the scope. Persisting cross-workspace
+ * data is blocked until ingress can prove scope (see the LUM-3023 plan's
+ * open blockers); nothing in this module resolves ids against any workspace.
+ */
+
+import {
+  extractSlackChannelReferenceIds,
+  extractSlackUserMentionIds,
+  renderSlackTextForModel,
+  sanitizeSlackLabel,
+} from "@vellumai/slack-text";
+
+export interface SlackMentionLabelMaps {
+  /** Slack user id (`U…`/`W…`) to sanitized display label. */
+  users: Record<string, string>;
+  /** Slack conversation id (`C…`/`G…`/`D…`) to sanitized channel name. */
+  channels: Record<string, string>;
+}
+
+export interface SlackMentionSourceV1 {
+  /** Schema version marker; readers must reject unknown versions. */
+  v: 1;
+  /**
+   * Workspace the labels were resolved under, when ingress supplied it.
+   * `null` means the install's implicit single-workspace scope.
+   */
+  installTeamId: string | null;
+  /** The verbatim Slack event text, mention markup intact. */
+  rawText: string;
+  /** Ingress-resolved labels, filtered to ids present in `rawText`. */
+  labels: SlackMentionLabelMaps;
+  /**
+   * True when the stored message body is exactly the render of
+   * (`rawText`, `labels`), computed once at persist time. Only projectable
+   * rows may ever be re-rendered; false covers composed bodies (e.g. voice
+   * transcription prepended at ingress), edits that diverged, and any
+   * unexpected mismatch.
+   */
+  projectable: boolean;
+}
+
+/**
+ * Upper bound on persisted raw text, in UTF-8 bytes. Oversize input is
+ * REJECTED (the whole source is dropped), never truncated: truncation can
+ * split a mention token and silently change what the text parses as.
+ */
+export const MENTION_RAW_TEXT_MAX_BYTES = 8192;
+
+/** Per-label character cap, matching the renderer's sanitizer budget. */
+export const MENTION_LABEL_MAX_CHARS = 200;
+
+/**
+ * Per-map entry cap. Overflow drops entries deterministically from the end
+ * of the sorted key order, so the same input always persists the same maps.
+ */
+export const MENTION_LABEL_MAP_MAX_ENTRIES = 32;
+
+const CHANNEL_ID_RE = /^[CDG][A-Z0-9]{1,31}$/;
+const USER_ID_RE = /^[UW][A-Z0-9]{1,31}$/;
+const TEAM_ID_RE = /^[TE][A-Z0-9]{1,31}$/;
+
+/**
+ * Sanitize a label for persistence: the shared renderer normalization from
+ * `@vellumai/slack-text` (single source of truth, so persisted labels can
+ * never drift from render-time semantics), plus the persistence-only
+ * bounds this module owns: well-formedness rejection and a length cap.
+ * Returns `undefined` when the input is malformed or nothing usable remains.
+ */
+export function sanitizeMentionLabel(value: unknown): string | undefined {
+  if (typeof value !== "string" || !isWellFormedString(value)) {
+    return undefined;
+  }
+  const normalized = sanitizeSlackLabel(value);
+  if (!normalized) {
+    return undefined;
+  }
+  // Truncate on code-point boundaries: a UTF-16 `slice` can split a
+  // surrogate pair and persist a lone surrogate, violating the same
+  // well-formedness rule this module enforces on rawText.
+  const sanitized = [...normalized]
+    .slice(0, MENTION_LABEL_MAX_CHARS)
+    .join("")
+    .trim();
+  return sanitized.length > 0 ? sanitized : undefined;
+}
+
+function utf8ByteLength(value: string): number {
+  return new TextEncoder().encode(value).length;
+}
+
+/** Reject strings carrying unpaired surrogates (not valid UTF-8 material). */
+function isWellFormedString(value: string): boolean {
+  const withIsWellFormed = value as string & { isWellFormed?: () => boolean };
+  if (typeof withIsWellFormed.isWellFormed === "function") {
+    return withIsWellFormed.isWellFormed();
+  }
+  try {
+    encodeURIComponent(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildLabelMap(
+  ids: readonly string[],
+  provided: Record<string, unknown> | undefined,
+  idPattern: RegExp,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!provided) {
+    return out;
+  }
+  // Deterministic overflow: iterate ids in sorted order and stop at the cap.
+  const sortedIds = [...new Set(ids)].sort();
+  for (const id of sortedIds) {
+    if (Object.keys(out).length >= MENTION_LABEL_MAP_MAX_ENTRIES) {
+      break;
+    }
+    if (!idPattern.test(id)) {
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(provided, id)) {
+      continue;
+    }
+    const label = sanitizeMentionLabel(provided[id]);
+    // An id-shaped "label" is not a resolution; the renderer treats it as
+    // unresolved, so persisting it would only waste bytes.
+    if (!label || label === id) {
+      continue;
+    }
+    out[id] = label;
+  }
+  return out;
+}
+
+export interface BuildSlackMentionSourceInput {
+  /** The verbatim Slack event text. */
+  rawText: unknown;
+  /** Ingress-resolved user labels keyed by user id, unvalidated. */
+  userLabels?: Record<string, unknown>;
+  /** Ingress-resolved channel labels keyed by conversation id, unvalidated. */
+  channelLabels?: Record<string, unknown>;
+  /** Workspace scope the labels were resolved under, when ingress knows it. */
+  installTeamId?: unknown;
+  /**
+   * The message body text as it will be persisted, used to compute
+   * `projectable` (exact-render equality).
+   */
+  storedBodyText: string;
+}
+
+/**
+ * Validate ingress inputs into a persistable `SlackMentionSourceV1`, or
+ * `undefined` when the text carries no mention tokens or fails validation.
+ * All bounds are enforced here regardless of how trusted the caller is:
+ * this function is the persistence boundary for mention data.
+ */
+export function buildSlackMentionSource(
+  input: BuildSlackMentionSourceInput,
+): SlackMentionSourceV1 | undefined {
+  const { rawText, storedBodyText } = input;
+  if (typeof rawText !== "string" || rawText.length === 0) {
+    return undefined;
+  }
+  if (!isWellFormedString(rawText)) {
+    return undefined;
+  }
+  if (utf8ByteLength(rawText) > MENTION_RAW_TEXT_MAX_BYTES) {
+    return undefined;
+  }
+
+  const userIds = extractSlackUserMentionIds(rawText);
+  const channelIds = extractSlackChannelReferenceIds(rawText);
+  if (userIds.length === 0 && channelIds.length === 0) {
+    return undefined;
+  }
+
+  const labels: SlackMentionLabelMaps = {
+    users: buildLabelMap(userIds, input.userLabels, USER_ID_RE),
+    channels: buildLabelMap(channelIds, input.channelLabels, CHANNEL_ID_RE),
+  };
+
+  const installTeamId =
+    typeof input.installTeamId === "string" &&
+    TEAM_ID_RE.test(input.installTeamId)
+      ? input.installTeamId
+      : null;
+
+  return {
+    v: 1,
+    installTeamId,
+    rawText,
+    labels,
+    projectable:
+      renderMentionSourceText(rawText, labels) === storedBodyText.trim(),
+  };
+}
+
+/**
+ * Parse a persisted (or wire) value back into a validated
+ * `SlackMentionSourceV1`. Unknown versions, malformed shapes, and
+ * out-of-bounds data return `undefined` so readers fall back to stored text.
+ */
+export function readSlackMentionSource(
+  value: unknown,
+): SlackMentionSourceV1 | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (record.v !== 1) {
+    return undefined;
+  }
+  // A malformed labels container is a rejected shape, not "no labels": a
+  // value that lost its maps but kept `projectable: true` must fall back to
+  // stored text rather than project fallback labels over it.
+  const labels = asRecord(record.labels);
+  const users = asRecord(labels?.users);
+  const channels = asRecord(labels?.channels);
+  if (!labels || !users || !channels) {
+    return undefined;
+  }
+  const rebuilt = buildSlackMentionSource({
+    rawText: record.rawText,
+    userLabels: users,
+    channelLabels: channels,
+    installTeamId: record.installTeamId ?? undefined,
+    // `projectable` is a stored fact; re-deriving it needs the stored body,
+    // which readers do not always have. Preserve the persisted flag but only
+    // when it is a real boolean.
+    storedBodyText: "",
+  });
+  if (!rebuilt || typeof record.projectable !== "boolean") {
+    return undefined;
+  }
+  return { ...rebuilt, projectable: record.projectable };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function renderMentionSourceText(
+  rawText: string,
+  labels: SlackMentionLabelMaps,
+): string {
+  return renderSlackTextForModel(rawText, {
+    userLabels: labels.users,
+    channelLabels: labels.channels,
+  }).trim();
+}
+
+/**
+ * Pure, synchronous projection: render the persisted mention source when the
+ * row is projectable, otherwise return the stored text unchanged. No live
+ * cache or lookup participates; historical messages render the historical
+ * snapshot. Callers apply untrusted-content fencing AFTER this function
+ * (render-then-fence), matching the ingress pipeline's order.
+ */
+export function projectSlackMentionText(
+  source: SlackMentionSourceV1 | undefined,
+  storedText: string,
+): string {
+  if (!source || !source.projectable) {
+    return storedText;
+  }
+  const projected = renderMentionSourceText(source.rawText, source.labels);
+  return projected.length > 0 ? projected : storedText;
+}

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

@@ -11,6 +11,7 @@ import { credentialKey } from "../../../security/credential-key.js";
 import { getSecureKeyResultAsync } from "../../../security/secure-keys.js";
 import { BackendUnavailableError, ConfigError } from "../../../util/errors.js";
 import { getLogger } from "../../../util/logger.js";
+import { retryableCall } from "../retry-policy.js";
 
 const log = getLogger("telegram-api");
 
@@ -71,142 +72,58 @@ interface TelegramApiResponse<T> {
   parameters?: { retry_after?: number };
 }
 
-function isRetryable(status: number): boolean {
-  return status === 429 || status >= 500;
-}
-
-function computeDelay(
-  attempt: number,
-  initialBackoffMs: number,
-  retryAfterHeader: string | null,
-): number {
-  if (retryAfterHeader) {
-    const seconds = Number(retryAfterHeader);
-    if (Number.isFinite(seconds) && seconds > 0) {
-      return Math.min(seconds * 1000, 2_147_483_647);
-    }
-    const targetTime = new Date(retryAfterHeader).getTime();
-    if (Number.isFinite(targetTime)) {
-      const delayMs = targetTime - Date.now();
-      if (delayMs > 0) {
-        return Math.min(delayMs, 2_147_483_647);
-      }
-    }
+/** The Bot API envelope, or undefined when the body is not JSON. */
+function parseTelegramBody<T>(
+  body: string,
+): TelegramApiResponse<T> | undefined {
+  try {
+    return JSON.parse(body) as TelegramApiResponse<T>;
+  } catch {
+    return undefined;
   }
-  const exponential = initialBackoffMs * Math.pow(2, attempt - 1);
-  const jitter = Math.random() * exponential * 0.5;
-  return exponential + jitter;
 }
 
-async function retryableFetch<T>(
+function telegramCall<T>(
   method: string,
   doFetch: () => Promise<Response>,
 ): Promise<T> {
-  let lastError: Error | null = null;
-  let lastRetryAfter: string | null = null;
-
-  for (let attempt = 0; attempt <= TELEGRAM_DEFAULT_MAX_RETRIES; attempt++) {
-    if (attempt > 0) {
-      const delay = computeDelay(
-        attempt,
-        TELEGRAM_DEFAULT_INITIAL_BACKOFF_MS,
-        lastRetryAfter,
-      );
-      log.debug({ attempt, delay, method }, "Retrying Telegram API call");
-      await new Promise((r) => setTimeout(r, delay));
-    }
-
-    lastRetryAfter = null;
-
-    let response: Response;
-    try {
-      response = await doFetch();
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      lastError = new Error(
-        `Telegram ${method} request failed: ${redactBotTokens(message)}`,
-      );
-      log.warn(
-        { error: redactBotTokens(message), attempt, method },
-        "Telegram API fetch failed",
-      );
-      continue;
-    }
-
-    if (!isRetryable(response.status) && !response.ok) {
-      const body = await response.text().catch(() => "");
-      let description: string | undefined;
-      try {
-        const data = JSON.parse(body) as TelegramApiResponse<T>;
-        description = data.description;
-      } catch {
-        // not JSON
+  return retryableCall<T>({
+    provider: "Telegram",
+    operation: method,
+    maxRetries: TELEGRAM_DEFAULT_MAX_RETRIES,
+    initialBackoffMs: TELEGRAM_DEFAULT_INITIAL_BACKOFF_MS,
+    log,
+    doFetch,
+    // Telegram errors can echo the bot token, which is in the request URL.
+    redact: redactBotTokens,
+    detailFrom: (body) => parseTelegramBody<T>(body)?.description,
+    retryAfterFrom: (_response, body) => {
+      const retryAfter = parseTelegramBody<T>(body)?.parameters?.retry_after;
+      return retryAfter != null ? String(retryAfter) : null;
+    },
+    nonRetryableError: ({ message, detail }) =>
+      new TelegramNonRetryableError(message, detail),
+    decode: (body, response) => {
+      const data = parseTelegramBody<T>(body);
+      if (!data) {
+        throw new Error(
+          body
+            ? `Telegram ${method} failed: unparseable response body: ${redactBotTokens(body)}`
+            : `Telegram ${method} failed with status ${response.status}: empty response`,
+        );
       }
-      const message = description
-        ? `Telegram ${method} failed: ${description}`
-        : body
-          ? `Telegram ${method} failed with status ${response.status}: ${redactBotTokens(body)}`
-          : `Telegram ${method} failed with status ${response.status}`;
-
-      throw new TelegramNonRetryableError(message, description);
-    }
-
-    if (isRetryable(response.status)) {
-      const body = await response.text().catch(() => "");
-      let description: string | undefined;
-      let retryAfterParam: number | undefined;
-      try {
-        const data = JSON.parse(body) as TelegramApiResponse<T>;
-        description = data.description;
-        retryAfterParam = data.parameters?.retry_after;
-      } catch {
-        // not JSON
-      }
-      lastRetryAfter =
-        response.headers.get("retry-after") ??
-        (retryAfterParam != null ? String(retryAfterParam) : null);
-      lastError = new Error(
-        description
-          ? `Telegram ${method} failed: ${description}`
-          : body
-            ? `Telegram ${method} failed with status ${response.status}: ${redactBotTokens(body)}`
+      // A 200 can still carry a failure: the Bot API reports it in the
+      // envelope rather than the status.
+      if (!data.ok || data.result === undefined) {
+        throw new Error(
+          data.description
+            ? `Telegram ${method} failed: ${data.description}`
             : `Telegram ${method} failed with status ${response.status}`,
-      );
-      log.warn(
-        {
-          status: response.status,
-          attempt,
-          method,
-          retryAfter: lastRetryAfter,
-        },
-        "Telegram API returned retryable error",
-      );
-      continue;
-    }
-
-    const body = await response.text().catch(() => "");
-    let data: TelegramApiResponse<T>;
-    try {
-      data = JSON.parse(body) as TelegramApiResponse<T>;
-    } catch {
-      throw new Error(
-        body
-          ? `Telegram ${method} failed: unparseable response body: ${redactBotTokens(body)}`
-          : `Telegram ${method} failed with status ${response.status}: empty response`,
-      );
-    }
-    if (!data.ok || data.result === undefined) {
-      throw new Error(
-        data.description
-          ? `Telegram ${method} failed: ${data.description}`
-          : `Telegram ${method} failed with status ${response.status}`,
-      );
-    }
-
-    return data.result;
-  }
-
-  throw lastError ?? new Error(`Telegram ${method} failed after retries`);
+        );
+      }
+      return data.result;
+    },
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -250,7 +167,7 @@ export async function callTelegramBotApi<T>(
   body: Record<string, unknown>,
 ): Promise<T> {
   const botToken = await resolveBotToken();
-  return retryableFetch<T>(method, () =>
+  return telegramCall<T>(method, () =>
     fetch(`${TELEGRAM_API_BASE}/bot${botToken}/${method}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -268,7 +185,7 @@ export async function callTelegramBotApiMultipart<T>(
   form: FormData,
 ): Promise<T> {
   const botToken = await resolveBotToken();
-  return retryableFetch<T>(method, () =>
+  return telegramCall<T>(method, () =>
     fetch(`${TELEGRAM_API_BASE}/bot${botToken}/${method}`, {
       method: "POST",
       body: form,