@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/notifications/adapters/slack.ts

@@ -1,17 +1,34 @@
 /**
  * Slack channel adapter — delivers notifications to Slack DMs
- * by calling the Slack Web API directly.
+ * using native Card blocks for approval notifications.
+ *
+ * Approval notifications (access requests, tool approvals) render as a
+ * single Slack Card block with Approve/Reject action buttons, plus
+ * optional companion context blocks for details that exceed the card's
+ * character limits. Non-approval notifications use standard Block Kit
+ * text sections.
+ *
+ * Card block reference:
+ * https://docs.slack.dev/reference/block-kit/blocks/card-block
  */
 
 import { sendSlackReply } from "../../messaging/providers/slack/send.js";
+import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
 import { getLogger } from "../../util/logger.js";
 import {
-  buildAccessRequestIdentityLine,
   buildAccessRequestInviteDirective,
-  sanitizeIdentityField,
+  buildAccessRequestWarnings,
+  buildSlackMessagePermalink,
+  isSlackDmConversation,
+  parseAccessRequestPayload,
+  type ParsedAccessRequestPayload,
 } from "../access-request-copy.js";
 import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import { nonEmpty } from "../copy-composer.js";
+import {
+  nonEmpty,
+  sanitizeIdentityField,
+  sanitizeMessagePreview,
+} from "../notification-utils.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -24,6 +41,10 @@ import type {
 
 const log = getLogger("notif-adapter-slack");
 
+// ---------------------------------------------------------------------------
+// Text resolution
+// ---------------------------------------------------------------------------
+
 function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
   const deliveryText = nonEmpty(payload.copy.deliveryText);
   if (deliveryText) return deliveryText;
@@ -41,147 +62,270 @@ function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
   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) + "…";
+}
+
 // ---------------------------------------------------------------------------
-// Block Kit helpers for access request notifications
+// Slack Card block builders for approval notifications
 // ---------------------------------------------------------------------------
 
-/**
- * Build Block Kit blocks for an access request notification.
- *
- * Returns an array of Slack Block Kit block objects with structured layout:
- * - Header: "New access request"
- * - Section: requester identity details
- * - Optional context: message preview
- * - Context: approval code instructions + invite directive
- */
-function buildAccessRequestBlocks(payload: Record<string, unknown>): unknown[] {
-  const blocks: unknown[] = [];
+/** Build action buttons for a Slack Card block from approval metadata. */
+function buildCardActions(approval: ApprovalUIMetadata): unknown[] {
+  return approval.actions.map((action) => ({
+    type: "button",
+    text: { type: "plain_text", text: action.label, emoji: true },
+    action_id: `apr:${approval.requestId}:${action.id}`,
+    value: `apr:${approval.requestId}:${action.id}`,
+    ...(action.id === "reject" ? { style: "danger" } : { style: "primary" }),
+  }));
+}
 
-  // Header
-  blocks.push({
-    type: "header",
-    text: { type: "plain_text", text: "New access request", emoji: true },
-  });
+// ---------------------------------------------------------------------------
+// Access request card
+// ---------------------------------------------------------------------------
 
-  // Requester identity section
-  const identityLine = buildAccessRequestIdentityLine(payload);
-  blocks.push({
-    type: "section",
-    text: { type: "mrkdwn", text: identityLine },
-  });
+/** 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})`);
+  }
 
-  // Build fields for structured requester details
-  const fields: Array<{ type: "mrkdwn"; text: string }> = [];
+  if (p.sourceChannel) parts.push(`via ${p.sourceChannel}`);
 
-  const senderIdentifier = nonEmpty(
-    typeof payload.senderIdentifier === "string"
-      ? sanitizeIdentityField(payload.senderIdentifier)
-      : undefined,
-  );
-  if (senderIdentifier) {
-    fields.push({ type: "mrkdwn", text: `*Name:*\n${senderIdentifier}` });
+  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}"_`;
+    }
   }
+  return "Requesting access to the assistant";
+}
 
-  const actorUsername = nonEmpty(
-    typeof payload.actorUsername === "string"
-      ? sanitizeIdentityField(payload.actorUsername)
-      : undefined,
-  );
-  if (actorUsername) {
-    fields.push({ type: "mrkdwn", text: `*Username:*\n@${actorUsername}` });
+/** Source-channel context block with Slack permalink when available. */
+function buildSourceContextBlock(
+  p: ParsedAccessRequestPayload,
+): unknown | undefined {
+  if (p.sourceChannel !== "slack" || !p.conversationExternalId) {
+    return undefined;
   }
 
-  const sourceChannel = nonEmpty(
-    typeof payload.sourceChannel === "string"
-      ? payload.sourceChannel
-      : undefined,
-  );
-  if (sourceChannel) {
-    fields.push({ type: "mrkdwn", text: `*Channel:*\n${sourceChannel}` });
+  const permalink = p.messageTs
+    ? buildSlackMessagePermalink(p.conversationExternalId, p.messageTs)
+    : undefined;
+
+  let sourceText: string;
+  if (isSlackDmConversation(p.conversationExternalId)) {
+    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}>`;
   }
 
-  const actorExternalId = nonEmpty(
-    typeof payload.actorExternalId === "string"
-      ? sanitizeIdentityField(payload.actorExternalId)
-      : undefined,
+  return {
+    type: "context",
+    elements: [{ type: "mrkdwn", text: sourceText }],
+  };
+}
+
+/** Stable requester identifier context block (external ID when it adds info). */
+function buildRequesterIdBlock(
+  p: ParsedAccessRequestPayload,
+): unknown | undefined {
+  const safeExternalId = nonEmpty(
+    p.actorExternalId ? sanitizeIdentityField(p.actorExternalId) : undefined,
   );
-  if (actorExternalId && actorExternalId !== senderIdentifier) {
-    fields.push({ type: "mrkdwn", text: `*ID:*\n${actorExternalId}` });
-  }
+  if (!safeExternalId) return undefined;
 
-  if (fields.length > 0) {
-    blocks.push({
-      type: "section",
-      fields,
-    });
+  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
+  ) {
+    return undefined;
   }
 
-  // Previously revoked warning
-  const previousMemberStatus =
-    typeof payload.previousMemberStatus === "string"
-      ? payload.previousMemberStatus
+  return {
+    type: "context",
+    elements: [{ type: "mrkdwn", text: `ID: ${safeExternalId}` }],
+  };
+}
+
+/**
+ * Build Slack blocks for an access request using a native Card block.
+ *
+ * Layout:
+ *   Card — title + subtitle (identity) + body (preview) + actions + subtext (warnings)
+ *   Context — source permalink (when the request is from Slack)
+ *   Context — stable requester ID (when it adds info beyond subtitle)
+ *   Context — invite directive
+ *   Context — guardian verification note (conditional)
+ */
+function buildAccessRequestCardBlocks(
+  payload: ChannelDeliveryPayload,
+): unknown[] {
+  const approval = payload.approvalContext!;
+  const p = parseAccessRequestPayload(payload.contextPayload!);
+  const blocks: unknown[] = [];
+
+  const subtitle = buildAccessRequestSubtitle(p);
+  const body = buildAccessRequestBody(p);
+
+  const warnings = buildAccessRequestWarnings(p);
+  const subtext =
+    warnings.length > 0
+      ? truncate(warnings.map((w) => `:warning: ${w}`).join(" · "), 200)
       : undefined;
-  if (previousMemberStatus === "revoked") {
+
+  const card: Record<string, unknown> = {
+    type: "card",
+    title: { type: "plain_text", 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);
+  if (sourceContext) blocks.push(sourceContext);
+
+  const idBlock = buildRequesterIdBlock(p);
+  if (idBlock) blocks.push(idBlock);
+
+  blocks.push({
+    type: "context",
+    elements: [{ type: "mrkdwn", text: buildAccessRequestInviteDirective() }],
+  });
+
+  if (
+    (p.guardianResolutionSource === "vellum-anchor" ||
+      p.guardianResolutionSource === "none") &&
+    p.sourceChannel
+  ) {
     blocks.push({
       type: "context",
       elements: [
         {
           type: "mrkdwn",
-          text: ":warning: This user was previously revoked.",
+          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._`,
         },
       ],
     });
   }
 
-  // Divider before instructions
-  blocks.push({ type: "divider" });
+  return blocks;
+}
 
-  // Approval code instructions
-  const requestCode = nonEmpty(
-    typeof payload.requestCode === "string" ? payload.requestCode : undefined,
-  );
-  if (requestCode) {
-    const code = requestCode.toUpperCase();
+// ---------------------------------------------------------------------------
+// Tool approval card
+// ---------------------------------------------------------------------------
+
+/**
+ * Build Slack blocks for a tool approval notification using a native Card block.
+ *
+ * Layout:
+ *   Card — title + subtitle (tool + requester) + body (notification text) + actions
+ */
+function buildToolApprovalCardBlocks(
+  payload: ChannelDeliveryPayload,
+  messageText: string,
+): unknown[] {
+  const approval = payload.approvalContext!;
+  const blocks: unknown[] = [];
+
+  const details = approval.permissionDetails;
+  const toolName = details?.toolName;
+  const requester = details?.requesterIdentifier;
+  let subtitle: string | undefined;
+  if (toolName && requester) {
+    subtitle = truncate(`${toolName} — requested by ${requester}`, 150);
+  } else if (toolName) {
+    subtitle = truncate(toolName, 150);
+  }
+
+  const needsOverflow = messageText.length > 200;
+  const card: Record<string, unknown> = {
+    type: "card",
+    title: {
+      type: "plain_text",
+      text: details ? "Tool Approval" : "Approval Request",
+    },
+    body: {
+      type: "mrkdwn",
+      text: needsOverflow ? truncate(messageText, 197) + " ↓" : messageText,
+    },
+    actions: buildCardActions(approval),
+  };
+  if (subtitle) card.subtitle = { type: "mrkdwn", text: subtitle };
+  blocks.push(card);
+
+  // When the message exceeds the card body limit, show the full text in a
+  // companion section so the approver can see the complete command/context.
+  if (needsOverflow) {
     blocks.push({
       type: "section",
-      text: {
-        type: "mrkdwn",
-        text: `Reply *${code} approve* to grant access or *${code} reject* to deny.`,
-      },
+      text: { type: "mrkdwn", text: truncate(messageText, 3000) },
     });
   }
 
-  // Invite directive
-  const inviteDirective = buildAccessRequestInviteDirective();
-  blocks.push({
-    type: "context",
-    elements: [{ type: "mrkdwn", text: inviteDirective }],
-  });
+  return blocks;
+}
 
-  // Guardian verification note
-  const guardianResolutionSource =
-    typeof payload.guardianResolutionSource === "string"
-      ? payload.guardianResolutionSource
-      : undefined;
+// ---------------------------------------------------------------------------
+// Unified approval block dispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Build Slack blocks for any notification carrying approval context.
+ * Dispatches to the appropriate card builder based on source event type.
+ */
+function buildApprovalNotificationBlocks(
+  payload: ChannelDeliveryPayload,
+  messageText: string,
+): unknown[] {
   if (
-    (guardianResolutionSource === "vellum-anchor" ||
-      guardianResolutionSource === "none") &&
-    sourceChannel
+    payload.sourceEventName === "ingress.access_request" &&
+    payload.contextPayload != null
   ) {
-    blocks.push({
-      type: "context",
-      elements: [
-        {
-          type: "mrkdwn",
-          text: `_You haven't verified your identity on ${sourceChannel} yet. If this was you trying to message your assistant, say "help me verify as guardian on ${sourceChannel}" to set up direct access._`,
-        },
-      ],
-    });
+    return buildAccessRequestCardBlocks(payload);
   }
 
-  return blocks;
+  return buildToolApprovalCardBlocks(payload, messageText);
 }
 
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
 export class SlackAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "slack";
 
@@ -203,15 +347,10 @@ export class SlackAdapter implements ChannelAdapter {
 
     const messageText = resolveSlackMessageText(payload);
 
-    // Build Block Kit blocks for access request notifications
-    const isAccessRequest =
-      payload.sourceEventName === "ingress.access_request" &&
-      payload.contextPayload != null;
-
     try {
-      const result = isAccessRequest
+      const result = payload.approvalContext
         ? await sendSlackReply(chatId, messageText, {
-            blocks: buildAccessRequestBlocks(payload.contextPayload!),
+            blocks: buildApprovalNotificationBlocks(payload, messageText),
           })
         : await sendSlackReply(chatId, messageText, { useBlocks: true });
 

package/src/notifications/adapters/telegram.ts

@@ -2,19 +2,17 @@
  * Telegram channel adapter — delivers notifications to Telegram chats
  * by calling the Telegram Bot API directly.
  *
- * For access request notifications, inline keyboard buttons ("Approve once",
- * "Reject") are attached so the guardian can act without typing a command.
- * If the rich delivery fails, the adapter falls back to plain text with
- * typed-command instructions.
+ * When the delivery payload carries an `approvalContext` (built centrally
+ * by the broadcaster), inline keyboard buttons ("Approve once", "Reject")
+ * are attached. If the rich delivery fails, the adapter falls back to
+ * plain text with typed-command instructions.
  */
 
 import { sendTelegramReply } from "../../messaging/providers/telegram-bot/send.js";
-import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
 import { ConfigError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
-import { buildAccessRequestContractText } from "../access-request-copy.js";
 import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import { nonEmpty } from "../copy-composer.js";
+import { nonEmpty } from "../notification-utils.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -42,34 +40,6 @@ function resolveTelegramMessageText(payload: ChannelDeliveryPayload): string {
   return payload.sourceEventName.replace(/[._]/g, " ");
 }
 
-/**
- * Build an {@link ApprovalUIMetadata} for an access request so the delivery
- * renders inline keyboard buttons in the Telegram message.
- *
- * Returns `undefined` when the context payload is missing the required
- * `requestId`, in which case the caller should fall back to plain text.
- */
-function buildAccessRequestApproval(
-  contextPayload: Record<string, unknown>,
-): ApprovalUIMetadata | undefined {
-  const requestId =
-    typeof contextPayload.requestId === "string"
-      ? contextPayload.requestId
-      : undefined;
-  if (!requestId) return undefined;
-
-  const plainTextFallback = buildAccessRequestContractText(contextPayload);
-
-  return {
-    requestId,
-    actions: [
-      { id: "approve_once", label: "Approve once" },
-      { id: "reject", label: "Reject" },
-    ],
-    plainTextFallback,
-  };
-}
-
 export class TelegramAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "telegram";
 
@@ -90,14 +60,7 @@ export class TelegramAdapter implements ChannelAdapter {
     }
 
     const messageText = resolveTelegramMessageText(payload);
-
-    const isAccessRequest =
-      payload.sourceEventName === "ingress.access_request" &&
-      payload.contextPayload != null;
-
-    const approval = isAccessRequest
-      ? buildAccessRequestApproval(payload.contextPayload!)
-      : undefined;
+    const approval = payload.approvalContext;
 
     try {
       if (approval) {
@@ -108,7 +71,7 @@ export class TelegramAdapter implements ChannelAdapter {
 
           log.info(
             { sourceEventName: payload.sourceEventName, chatId },
-            "Telegram access request notification delivered with inline buttons",
+            "Telegram approval notification delivered with inline buttons",
           );
 
           return { success: true };

package/src/notifications/approval-card-builder.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared builder for guardian approval card seed content blocks.
+ *
+ * Both access-request and tool-approval notifications render a Surface card
+ * with Approve/Reject buttons in the Vellum in-app channel. This module
+ * provides the shared construction logic so each notification type only
+ * supplies its domain-specific data (title, subtitle, metadata, etc.)
+ * without duplicating the card structure or action wiring.
+ *
+ * The card data shape matches `CardSurfaceData` from
+ * `daemon/message-types/surfaces.ts`: `{ title, subtitle, body, metadata }`.
+ * Actions use the canonical `apr:<requestId>:<action>` callback format
+ * consumed by `surface-action-routes.ts` → `processGuardianDecision`.
+ */
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+export interface ApprovalCardParams {
+  /** Prefix for `surfaceId` — combined with `requestId` to form e.g. "access-request-abc123". */
+  surfaceIdPrefix: string;
+  /** Top-level card title shown in the surface header (e.g. "Access Request", "Tool Approval"). */
+  cardTitle: string;
+  /** Primary line inside the card (typically the requester's display name). */
+  requesterName: string;
+  /** Secondary line below the requester name (e.g. "Requesting access to the assistant"). */
+  subtitle: string;
+  /** Markdown body — blockquotes, warnings, links, etc. */
+  body: string;
+  /** Key-value metadata grid rendered below the body. */
+  metadata: Array<{ label: string; value: string }>;
+  /** When present, Approve/Reject buttons are wired with `apr:<requestId>:*` action IDs. */
+  requestId?: string;
+  /** Plain-text content for the fallback `text` block. */
+  fallbackText: string;
+}
+
+// ── Builder ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a `[ui_surface, text]` block pair for a guardian approval notification.
+ *
+ * The `ui_surface` block renders as a card with Approve/Reject buttons in
+ * clients that support Surface rendering. The `text` block provides a
+ * plain-text fallback for older clients, search indexing, and CLI display.
+ */
+export function buildApprovalCardBlocks(params: ApprovalCardParams): unknown[] {
+  const {
+    surfaceIdPrefix,
+    cardTitle,
+    requesterName,
+    subtitle,
+    body,
+    metadata,
+    requestId,
+    fallbackText,
+  } = params;
+
+  const actions = requestId
+    ? [
+        {
+          id: `apr:${requestId}:approve_once`,
+          label: "Approve",
+          style: "primary",
+        },
+        {
+          id: `apr:${requestId}:reject`,
+          label: "Reject",
+          style: "destructive",
+        },
+      ]
+    : undefined;
+
+  const surfaceBlock = {
+    type: "ui_surface" as const,
+    surfaceId: `${surfaceIdPrefix}-${requestId ?? "unknown"}`,
+    surfaceType: "card" as const,
+    title: cardTitle,
+    data: {
+      title: requesterName,
+      subtitle,
+      body,
+      metadata,
+    },
+    ...(actions ? { actions } : {}),
+  };
+
+  const textBlock = {
+    type: "text" as const,
+    text: fallbackText,
+  };
+
+  return [surfaceBlock, textBlock];
+}