@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/notifications/access-request-copy.ts

@@ -7,7 +7,6 @@
 
 import { z } from "zod";
 
-import { buildApprovalCardBlocks } from "./approval-card-builder.js";
 import {
   nonEmpty,
   sanitizeIdentityField,
@@ -312,74 +311,88 @@ export function buildAccessRequestContractText(
   return lines.join("\n");
 }
 
-// ── Seed content blocks (Surface-based rendering) ───────────────────────────
+// ── Card view model ─────────────────────────────────────────────────────────
 
 /**
- * Build structured content blocks for an access request notification seed
- * message. Produces a `ui_surface` card block that the web/macOS/iOS apps
- * render as an interactive card via `SurfaceRouter → CardSurface`, plus a
- * plain-text fallback block for search, CLI display, and backward-compatible
- * clients that don't support surfaces.
+ * Display-ready projection of an access request, shared by every renderer
+ * (the Vellum Surface card and the Slack Card block). It carries the
+ * sanitized, pre-computed facts each renderer needs — identity sanitizing,
+ * warnings, permalink, DM detection, preview sanitizing — so that projection
+ * lives in exactly one place. Renderers lay these facts out in their
+ * channel-native shape without re-deriving them.
  */
-export function buildAccessRequestSeedContentBlocks(
-  payload: Record<string, unknown>,
-): unknown[] {
-  const p = parseAccessRequestPayload(payload);
+export interface AccessRequestCardView {
+  /** Sanitized display name (actorDisplayName ?? senderIdentifier, else "Someone"). */
+  displayName: string;
+  /** Sanitized username, without the leading `@`. */
+  username: string | undefined;
+  /** Sanitized external ID. */
+  externalId: string | undefined;
+  sourceChannel: string | undefined;
+  conversationExternalId: string | undefined;
+  /** Whether the source Slack conversation is a DM. */
+  isSlackDm: boolean;
+  /** Slack permalink — present only for a slack source with conversation + ts. */
+  messagePermalink: string | undefined;
+  /** Sanitized message preview, or undefined when blank after sanitizing. */
+  messagePreview: string | undefined;
+  /** Human-readable trust/security warnings. */
+  warnings: string[];
+  guardianResolutionSource: string | undefined;
+  requestId: string | undefined;
+}
 
+/**
+ * Project a parsed access-request payload into display-ready card facts.
+ *
+ * The payload is parsed once upstream — the broadcaster resolves
+ * `accessRequestContext`, and the Surface seed path parses the raw payload —
+ * so this takes the parsed payload rather than re-parsing it.
+ */
+export function buildAccessRequestCardView(
+  p: ParsedAccessRequestPayload,
+): AccessRequestCardView {
   const rawName = nonEmpty(p.actorDisplayName) ?? nonEmpty(p.senderIdentifier);
   const displayName = rawName ? sanitizeIdentityField(rawName) : "Someone";
 
-  const metadata: Array<{ label: string; value: string }> = [];
+  const rawUsername = nonEmpty(p.actorUsername);
+  const username = rawUsername ? sanitizeIdentityField(rawUsername) : undefined;
 
-  if (p.actorUsername) {
-    metadata.push({
-      label: "Username",
-      value: `@${sanitizeIdentityField(p.actorUsername)}`,
-    });
-  }
+  const rawExternalId = nonEmpty(p.actorExternalId);
+  const externalId = rawExternalId
+    ? sanitizeIdentityField(rawExternalId)
+    : undefined;
 
-  if (p.sourceChannel === "slack" && p.conversationExternalId) {
-    const isDm = isSlackDmConversation(p.conversationExternalId);
-    metadata.push({
-      label: "Source",
-      value: isDm
-        ? "Slack — Direct message"
-        : `Slack — #${p.conversationExternalId}`,
-    });
-  } else if (p.sourceChannel) {
-    metadata.push({ label: "Source", value: p.sourceChannel });
-  }
+  const sourceChannel = nonEmpty(p.sourceChannel);
+  const conversationExternalId = nonEmpty(p.conversationExternalId);
+  const messageTs = nonEmpty(p.messageTs);
 
-  const warnings = buildAccessRequestWarnings(p);
-  const bodyParts: string[] = [];
+  const isSlackDm =
+    sourceChannel === "slack" && conversationExternalId != null
+      ? isSlackDmConversation(conversationExternalId)
+      : false;
 
-  if (p.messagePreview) {
-    bodyParts.push(`> "${sanitizeMessagePreview(p.messagePreview)}"`);
-  }
-  for (const w of warnings) {
-    bodyParts.push(`⚠️ ${w}`);
-  }
-  if (p.sourceChannel === "slack" && p.conversationExternalId && p.messageTs) {
-    const permalink = buildSlackMessagePermalink(
-      p.conversationExternalId,
-      p.messageTs,
-    );
-    bodyParts.push(`[View message](${permalink})`);
-  }
+  const messagePermalink =
+    sourceChannel === "slack" && conversationExternalId && messageTs
+      ? buildSlackMessagePermalink(conversationExternalId, messageTs)
+      : undefined;
+
+  const rawPreview = nonEmpty(p.messagePreview);
+  const messagePreview = rawPreview
+    ? sanitizeMessagePreview(rawPreview) || undefined
+    : undefined;
 
-  const body =
-    bodyParts.length > 0
-      ? bodyParts.join("\n\n")
-      : "No additional context available.";
-
-  return buildApprovalCardBlocks({
-    surfaceIdPrefix: "access-request",
-    cardTitle: "Access Request",
-    requesterName: displayName,
-    subtitle: "Requesting access to the assistant",
-    body,
-    metadata,
-    requestId: p.requestId,
-    fallbackText: buildAccessRequestContractText(payload),
-  });
+  return {
+    displayName,
+    username,
+    externalId,
+    sourceChannel,
+    conversationExternalId,
+    isSlackDm,
+    messagePermalink,
+    messagePreview,
+    warnings: buildAccessRequestWarnings(p),
+    guardianResolutionSource: nonEmpty(p.guardianResolutionSource),
+    requestId: nonEmpty(p.requestId),
+  };
 }

package/src/notifications/adapters/shared.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared adapter utilities — functions used by multiple channel adapters.
+ */
+
+import { isConversationSeedSane } from "../conversation-seed-composer.js";
+import { nonEmpty } from "../notification-utils.js";
+import type { ChannelDeliveryPayload } from "../types.js";
+
+/**
+ * Resolve the primary message text for a notification delivery.
+ *
+ * Cascade: deliveryText → conversationSeedMessage → body → title → event name.
+ */
+export function resolveMessageText(payload: ChannelDeliveryPayload): string {
+  const deliveryText = nonEmpty(payload.copy.deliveryText);
+  if (deliveryText) return deliveryText;
+
+  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
+    return payload.copy.conversationSeedMessage.trim();
+  }
+
+  const body = nonEmpty(payload.copy.body);
+  if (body) return body;
+
+  const title = nonEmpty(payload.copy.title);
+  if (title) return title;
+
+  return payload.sourceEventName.replace(/[._]/g, " ");
+}

package/src/notifications/adapters/slack.ts

@@ -16,19 +16,11 @@ import { sendSlackReply } from "../../messaging/providers/slack/send.js";
 import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
 import { getLogger } from "../../util/logger.js";
 import {
+  type AccessRequestCardView,
+  buildAccessRequestCardView,
   buildAccessRequestInviteDirective,
-  buildAccessRequestWarnings,
-  buildSlackMessagePermalink,
-  isSlackDmConversation,
-  parseAccessRequestPayload,
-  type ParsedAccessRequestPayload,
 } from "../access-request-copy.js";
-import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import {
-  nonEmpty,
-  sanitizeIdentityField,
-  sanitizeMessagePreview,
-} from "../notification-utils.js";
+import { truncate } from "../notification-utils.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -38,36 +30,10 @@ import type {
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
+import { resolveMessageText } from "./shared.js";
 
 const log = getLogger("notif-adapter-slack");
 
-// ---------------------------------------------------------------------------
-// Text resolution
-// ---------------------------------------------------------------------------
-
-function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
-  const deliveryText = nonEmpty(payload.copy.deliveryText);
-  if (deliveryText) return deliveryText;
-
-  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
-    return payload.copy.conversationSeedMessage.trim();
-  }
-
-  const body = nonEmpty(payload.copy.body);
-  if (body) return body;
-
-  const title = nonEmpty(payload.copy.title);
-  if (title) return title;
-
-  return payload.sourceEventName.replace(/[._]/g, " ");
-}
-
-/** Truncate to `maxLength`, appending "…" when exceeded. */
-function truncate(text: string, maxLength: number): string {
-  if (text.length <= maxLength) return text;
-  return text.slice(0, maxLength - 1) + "…";
-}
-
 // ---------------------------------------------------------------------------
 // Slack Card block builders for approval notifications
 // ---------------------------------------------------------------------------
@@ -88,57 +54,48 @@ function buildCardActions(approval: ApprovalUIMetadata): unknown[] {
 // ---------------------------------------------------------------------------
 
 /** Concise requester identity for the card subtitle (≤150 chars). */
-function buildAccessRequestSubtitle(p: ParsedAccessRequestPayload): string {
-  const rawName = nonEmpty(p.actorDisplayName) ?? nonEmpty(p.senderIdentifier);
-  const displayName = rawName ? sanitizeIdentityField(rawName) : "Someone";
-  const parts = [displayName];
-
-  const username = nonEmpty(p.actorUsername);
-  if (username) {
-    const safe = sanitizeIdentityField(username);
-    if (safe !== displayName) parts.push(`(@${safe})`);
+function buildAccessRequestSubtitle(view: AccessRequestCardView): string {
+  const parts = [view.displayName];
+
+  if (view.username && view.username !== view.displayName) {
+    parts.push(`(@${view.username})`);
   }
 
-  if (p.sourceChannel) parts.push(`via ${p.sourceChannel}`);
+  if (view.sourceChannel) parts.push(`via ${view.sourceChannel}`);
 
   return truncate(parts.join(" "), 150);
 }
 
 /** Card body: message preview when available, otherwise a default label. */
-function buildAccessRequestBody(p: ParsedAccessRequestPayload): string {
-  if (p.messagePreview) {
-    const sanitized = sanitizeMessagePreview(p.messagePreview);
-    if (sanitized) {
-      // Truncate content before wrapping so formatting chars stay balanced.
-      // Wrapper `> _"..."_` is 6 chars; reserve space for them.
-      const trimmed = truncate(sanitized, 200 - 6);
-      return `> _"${trimmed}"_`;
-    }
+function buildAccessRequestBody(view: AccessRequestCardView): string {
+  if (view.messagePreview) {
+    // Truncate content before wrapping so formatting chars stay balanced.
+    // Wrapper `> _"..."_` is 6 chars; reserve space for them.
+    const trimmed = truncate(view.messagePreview, 200 - 6);
+    return `> _"${trimmed}"_`;
   }
   return "Requesting access to the assistant";
 }
 
 /** Source-channel context block with Slack permalink when available. */
 function buildSourceContextBlock(
-  p: ParsedAccessRequestPayload,
+  view: AccessRequestCardView,
 ): unknown | undefined {
-  if (p.sourceChannel !== "slack" || !p.conversationExternalId) {
+  if (view.sourceChannel !== "slack" || !view.conversationExternalId) {
     return undefined;
   }
 
-  const permalink = p.messageTs
-    ? buildSlackMessagePermalink(p.conversationExternalId, p.messageTs)
-    : undefined;
+  const permalink = view.messagePermalink;
 
   let sourceText: string;
-  if (isSlackDmConversation(p.conversationExternalId)) {
+  if (view.isSlackDm) {
     sourceText = permalink
       ? `Source: Slack — Direct message · <${permalink}|View message>`
       : "Source: Slack — Direct message";
   } else {
     sourceText = permalink
-      ? `Source: Slack — <#${p.conversationExternalId}> · <${permalink}|View message>`
-      : `Source: Slack — <#${p.conversationExternalId}>`;
+      ? `Source: Slack — <#${view.conversationExternalId}> · <${permalink}|View message>`
+      : `Source: Slack — <#${view.conversationExternalId}>`;
   }
 
   return {
@@ -149,27 +106,12 @@ function buildSourceContextBlock(
 
 /** Stable requester identifier context block (external ID when it adds info). */
 function buildRequesterIdBlock(
-  p: ParsedAccessRequestPayload,
+  view: AccessRequestCardView,
 ): unknown | undefined {
-  const safeExternalId = nonEmpty(
-    p.actorExternalId ? sanitizeIdentityField(p.actorExternalId) : undefined,
-  );
+  const safeExternalId = view.externalId;
   if (!safeExternalId) return undefined;
 
-  const displayedName = nonEmpty(
-    p.actorDisplayName
-      ? sanitizeIdentityField(p.actorDisplayName)
-      : p.senderIdentifier
-        ? sanitizeIdentityField(p.senderIdentifier)
-        : undefined,
-  );
-  const displayedUsername = nonEmpty(
-    p.actorUsername ? sanitizeIdentityField(p.actorUsername) : undefined,
-  );
-  if (
-    safeExternalId === displayedName ||
-    safeExternalId === displayedUsername
-  ) {
+  if (safeExternalId === view.displayName || safeExternalId === view.username) {
     return undefined;
   }
 
@@ -183,7 +125,8 @@ function buildRequesterIdBlock(
  * Build Slack blocks for an access request using a native Card block.
  *
  * Layout:
- *   Card — title + subtitle (identity) + body (preview) + actions + subtext (warnings)
+ *   Card — title + subtitle (identity) + body (preview) + actions
+ *   Context — security warnings (revoked/restricted/stranger), when present
  *   Context — source permalink (when the request is from Slack)
  *   Context — stable requester ID (when it adds info beyond subtitle)
  *   Context — invite directive
@@ -193,32 +136,42 @@ function buildAccessRequestCardBlocks(
   payload: ChannelDeliveryPayload,
 ): unknown[] {
   const approval = payload.approvalContext!;
-  const p = parseAccessRequestPayload(payload.contextPayload!);
+  const view = buildAccessRequestCardView(payload.accessRequestContext!);
   const blocks: unknown[] = [];
 
-  const subtitle = buildAccessRequestSubtitle(p);
-  const body = buildAccessRequestBody(p);
+  const subtitle = buildAccessRequestSubtitle(view);
+  const body = buildAccessRequestBody(view);
 
-  const warnings = buildAccessRequestWarnings(p);
-  const subtext =
-    warnings.length > 0
-      ? truncate(warnings.map((w) => `:warning: ${w}`).join(" · "), 200)
+  const warningsText =
+    view.warnings.length > 0
+      ? truncate(view.warnings.map((w) => `:warning: ${w}`).join(" · "), 200)
       : undefined;
 
   const card: Record<string, unknown> = {
     type: "card",
-    title: { type: "plain_text", text: "Access Request" },
+    title: { type: "mrkdwn", text: "Access Request" },
     subtitle: { type: "mrkdwn", text: subtitle },
     body: { type: "mrkdwn", text: body },
     actions: buildCardActions(approval),
   };
-  if (subtext) card.subtext = { type: "mrkdwn", text: subtext };
   blocks.push(card);
 
-  const sourceContext = buildSourceContextBlock(p);
+  // Security warnings (revoked / restricted / stranger) render in a context
+  // block under the card. Slack's card block schema has no field for them
+  // (https://docs.slack.dev/reference/block-kit/blocks/card-block) and Slack
+  // silently drops unknown card fields, so a dedicated block is needed to
+  // surface them to the guardian.
+  if (warningsText) {
+    blocks.push({
+      type: "context",
+      elements: [{ type: "mrkdwn", text: warningsText }],
+    });
+  }
+
+  const sourceContext = buildSourceContextBlock(view);
   if (sourceContext) blocks.push(sourceContext);
 
-  const idBlock = buildRequesterIdBlock(p);
+  const idBlock = buildRequesterIdBlock(view);
   if (idBlock) blocks.push(idBlock);
 
   blocks.push({
@@ -227,16 +180,16 @@ function buildAccessRequestCardBlocks(
   });
 
   if (
-    (p.guardianResolutionSource === "vellum-anchor" ||
-      p.guardianResolutionSource === "none") &&
-    p.sourceChannel
+    (view.guardianResolutionSource === "vellum-anchor" ||
+      view.guardianResolutionSource === "none") &&
+    view.sourceChannel
   ) {
     blocks.push({
       type: "context",
       elements: [
         {
           type: "mrkdwn",
-          text: `_You haven't verified your identity on ${p.sourceChannel} yet. If this was you trying to message your assistant, say "help me verify as guardian on ${p.sourceChannel}" to set up direct access._`,
+          text: `_You haven't verified your identity on ${view.sourceChannel} yet. If this was you trying to message your assistant, say "help me verify as guardian on ${view.sourceChannel}" to set up direct access._`,
         },
       ],
     });
@@ -276,7 +229,7 @@ function buildToolApprovalCardBlocks(
   const card: Record<string, unknown> = {
     type: "card",
     title: {
-      type: "plain_text",
+      type: "mrkdwn",
       text: details ? "Tool Approval" : "Approval Request",
     },
     body: {
@@ -307,14 +260,16 @@ function buildToolApprovalCardBlocks(
 /**
  * Build Slack blocks for any notification carrying approval context.
  * Dispatches to the appropriate card builder based on source event type.
+ *
+ * Exported for characterization tests of the approval-card block output.
  */
-function buildApprovalNotificationBlocks(
+export function buildApprovalNotificationBlocks(
   payload: ChannelDeliveryPayload,
   messageText: string,
 ): unknown[] {
   if (
     payload.sourceEventName === "ingress.access_request" &&
-    payload.contextPayload != null
+    payload.accessRequestContext != null
   ) {
     return buildAccessRequestCardBlocks(payload);
   }
@@ -345,7 +300,7 @@ export class SlackAdapter implements ChannelAdapter {
       };
     }
 
-    const messageText = resolveSlackMessageText(payload);
+    const messageText = resolveMessageText(payload);
 
     try {
       const result = payload.approvalContext

package/src/notifications/adapters/telegram.ts

@@ -11,8 +11,6 @@
 import { sendTelegramReply } from "../../messaging/providers/telegram-bot/send.js";
 import { ConfigError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
-import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import { nonEmpty } from "../notification-utils.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -20,26 +18,10 @@ import type {
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
+import { resolveMessageText } from "./shared.js";
 
 const log = getLogger("notif-adapter-telegram");
 
-function resolveTelegramMessageText(payload: ChannelDeliveryPayload): string {
-  const deliveryText = nonEmpty(payload.copy.deliveryText);
-  if (deliveryText) return deliveryText;
-
-  if (isConversationSeedSane(payload.copy.conversationSeedMessage)) {
-    return payload.copy.conversationSeedMessage.trim();
-  }
-
-  const body = nonEmpty(payload.copy.body);
-  if (body) return body;
-
-  const title = nonEmpty(payload.copy.title);
-  if (title) return title;
-
-  return payload.sourceEventName.replace(/[._]/g, " ");
-}
-
 export class TelegramAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "telegram";
 
@@ -59,7 +41,7 @@ export class TelegramAdapter implements ChannelAdapter {
       };
     }
 
-    const messageText = resolveTelegramMessageText(payload);
+    const messageText = resolveMessageText(payload);
     const approval = payload.approvalContext;
 
     try {