@vellumai/assistant 0.10.5-staging.2 → 0.10.5

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

@@ -151,13 +151,15 @@ export interface SlackSendResult {
  * Those errors fault the Block Kit payload, not the target — the retry repeats
  * the *same* operation (same `chat.update` ts, same `chat.postMessage` thread)
  * without blocks, so it edits/posts in place rather than spawning a second
- * message. Any other error propagates to the caller.
+ * message. `fallbackText` replaces the message text on that retry (used to
+ * re-attach reply instructions whose Block Kit equivalent was dropped). Any
+ * other error propagates to the caller.
  */
 async function sendWithBlockFallback(
   method: string,
   baseBody: Record<string, unknown>,
   blocks: KnownBlock[],
-  options: { fallbackWithoutBlocks: boolean },
+  options: { fallbackWithoutBlocks: boolean; fallbackText?: string },
 ): Promise<SlackSendResult> {
   try {
     const result = await callSlackApi(
@@ -177,13 +179,36 @@ async function sendWithBlockFallback(
         { method, slackError: err.slackError },
         "Slack rejected blocks; retrying without blocks",
       );
-      const result = await callSlackApi(method, baseBody);
+      const retryBody =
+        options.fallbackText !== undefined
+          ? { ...baseBody, text: options.fallbackText }
+          : baseBody;
+      const result = await callSlackApi(method, retryBody);
       return { ok: true, ts: result.ts };
     }
     throw err;
   }
 }
 
+/**
+ * Text for the block-free retry of an approval prompt. Dropping an approval's
+ * blocks removes its Approve/Reject buttons, so the retry re-attaches the
+ * plain-text reply instructions to keep the message actionable. Returns
+ * `undefined` when the approval has no usable instructions — such a prompt
+ * must not be retried bare, since a message with no way to respond is worse
+ * than a failed delivery the delivery layer can surface.
+ */
+function buildApprovalFallbackText(
+  text: string,
+  approval: ApprovalUIMetadata,
+): string | undefined {
+  const instructions = approval.plainTextFallback.trim();
+  if (instructions.length === 0) {
+    return undefined;
+  }
+  return text.includes(instructions) ? text : `${text}\n\n${instructions}`;
+}
+
 /**
  * Send a Slack text message with optional Block Kit formatting.
  *
@@ -219,29 +244,40 @@ export async function sendSlackReply(
   }
 
   const postBase: Record<string, unknown> = { channel: chatId, text };
-  if (options?.threadTs) postBase.thread_ts = options.threadTs;
+  if (options?.threadTs) {
+    postBase.thread_ts = options.threadTs;
+  }
+
+  // Approval prompts carry their action buttons in `blocks`. When Slack
+  // rejects the payload, the block-free retry re-attaches the plain-text
+  // reply instructions so the recipient can still act by text reply; an
+  // approval without usable instructions is never retried bare.
+  const approvalFallbackText = options?.approval
+    ? buildApprovalFallbackText(text, options.approval)
+    : undefined;
+  const fallbackOptions = {
+    fallbackWithoutBlocks:
+      !options?.approval || approvalFallbackText !== undefined,
+    fallbackText: approvalFallbackText,
+  };
 
   if (options?.ephemeral) {
-    if (!options.user)
+    if (!options.user) {
       throw new Error("user is required for ephemeral messages");
+    }
     return sendWithBlockFallback(
       "chat.postEphemeral",
       { ...postBase, user: options.user },
       blocks,
-      { fallbackWithoutBlocks: !options.approval },
+      fallbackOptions,
     );
   }
 
-  // Approval prompts carry their action buttons in `blocks`; dropping them when
-  // Slack rejects the payload would post a card with no way to respond, so only
-  // non-approval posts fall back to a block-free retry.
   const result = await sendWithBlockFallback(
     "chat.postMessage",
     postBase,
     blocks,
-    {
-      fallbackWithoutBlocks: !options?.approval,
-    },
+    fallbackOptions,
   );
   log.info({ chatId, hasThreadTs: !!options?.threadTs }, "Slack message sent");
   return result;

package/src/notifications/README.md

@@ -57,7 +57,7 @@ Hard invariants that the LLM cannot override:
 
 **Post-generation enforcement** (`decision-engine.ts`):
 
-- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them.
+- **Guardian question request-code enforcement** — `enforceGuardianRequestCode()` ensures request-code instructions (approve/reject or free-text answer) appear in all `guardian.question` notification copy, even when the LLM omits them. Exception: for approval-mode questions the Slack adapter renders an interactive card with Approve/Reject buttons, so Slack copy is instead **stripped** of request-code instructions and bare code mentions (`stripGuardianRequestCodeInstructions()`).
 - **Access-request instruction enforcement** — `enforceAccessRequestInstructions()` validates that `ingress.access_request` copy contains: (1) the request-code approve/reject directive, (2) the exact "open invite flow" phrase. If any required element is missing, the full deterministic contract text is appended. This prevents model-generated copy from dropping security-critical action directives.
 
 **Pre-send gate checks** (`deterministic-checks.ts`) — these all depend on the decision, so they run here, after it:

package/src/notifications/adapters/slack.ts

@@ -3,10 +3,10 @@
  * 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.
+ * single Slack Card block with Approve/Reject action buttons. Text that
+ * exceeds the card body's 200-character cap continues in a companion
+ * section block below the card. Non-approval notifications use standard
+ * Block Kit text sections.
  *
  * Card block reference:
  * https://docs.slack.dev/reference/block-kit/blocks/card-block
@@ -204,11 +204,40 @@ function buildAccessRequestCardBlocks(
 // Tool approval card
 // ---------------------------------------------------------------------------
 
+/** Slack caps a card block's `body` text at 200 characters. */
+const CARD_BODY_MAX_LENGTH = 200;
+
+/** Marker signalling the card body continues in the section below. */
+const CARD_BODY_CONTINUATION_MARKER = " ↓";
+
+/**
+ * Split message text so the head fits Slack's card body cap (marker
+ * included) and the tail continues in a companion section below the card.
+ * Splits on the last whitespace inside the budget when there is one, so
+ * neither piece cuts mid-word. Text within the cap needs no split.
+ */
+function splitAtCardBodyLimit(text: string): { head: string; tail?: string } {
+  if (text.length <= CARD_BODY_MAX_LENGTH) {
+    return { head: text };
+  }
+
+  const budget = CARD_BODY_MAX_LENGTH - CARD_BODY_CONTINUATION_MARKER.length;
+  const window = text.slice(0, budget + 1);
+  const lastWhitespace = window.search(/\s\S*$/);
+  const cut = lastWhitespace > 0 ? lastWhitespace : budget;
+
+  return {
+    head: text.slice(0, cut).trimEnd() + CARD_BODY_CONTINUATION_MARKER,
+    tail: text.slice(cut).trimStart(),
+  };
+}
+
 /**
  * Build Slack blocks for a tool approval notification using a native Card block.
  *
  * Layout:
  *   Card — title + subtitle (tool + requester) + body (notification text) + actions
+ *   Section — continuation of body text exceeding the card's 200-char cap
  */
 function buildToolApprovalCardBlocks(
   payload: ChannelDeliveryPayload,
@@ -227,28 +256,25 @@ function buildToolApprovalCardBlocks(
     subtitle = truncate(toolName, 150);
   }
 
-  const needsOverflow = messageText.length > 200;
+  const { head, tail } = splitAtCardBodyLimit(messageText);
   const card: CardBlock = {
     type: "card",
     title: {
       type: "mrkdwn",
       text: details ? "Tool Approval" : "Approval Request",
     },
-    body: {
-      type: "mrkdwn",
-      text: needsOverflow ? truncate(messageText, 197) + " ↓" : messageText,
-    },
+    body: { type: "mrkdwn", text: head },
     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) {
+  // The companion section carries only the remainder — repeating the full
+  // text would render the same message twice (once in the card, once below).
+  if (tail) {
     blocks.push({
       type: "section",
-      text: { type: "mrkdwn", text: truncate(messageText, 3000) },
+      text: { type: "mrkdwn", text: truncate(`… ${tail}`, 3000) },
     });
   }
 
@@ -305,9 +331,14 @@ export class SlackAdapter implements ChannelAdapter {
     const messageText = resolveMessageText(payload);
 
     try {
+      // `approval` rides along with the prebuilt card blocks so the send
+      // layer treats a rejected Block Kit payload as an approval prompt:
+      // its block-free retry re-attaches `plainTextFallback` reply
+      // instructions instead of posting text with no way to respond.
       const result = payload.approvalContext
         ? await sendSlackReply(chatId, messageText, {
             blocks: buildApprovalNotificationBlocks(payload, messageText),
+            approval: payload.approvalContext,
           })
         : await sendSlackReply(chatId, messageText, { useBlocks: true });
 

package/src/notifications/broadcaster.ts

@@ -28,10 +28,7 @@ import {
   updateDeliveryStatus,
 } from "./deliveries-store.js";
 import { resolveDestinations } from "./destination-resolver.js";
-import {
-  parseGuardianQuestionPayload,
-  resolveGuardianInstructionModeFromPayload,
-} from "./guardian-question-mode.js";
+import { parseInteractiveApprovalPayload } from "./guardian-question-mode.js";
 import { nonEmpty } from "./notification-utils.js";
 import type { NotificationSignal } from "./signal.js";
 import type {
@@ -59,13 +56,17 @@ function resolveApprovalContext(
   signal: NotificationSignal,
 ): ApprovalUIMetadata | undefined {
   const payload = signal.contextPayload;
-  if (!payload) return undefined;
+  if (!payload) {
+    return undefined;
+  }
 
   if (signal.sourceEventName === "ingress.access_request") {
     const requestId = nonEmpty(
       typeof payload.requestId === "string" ? payload.requestId : undefined,
     );
-    if (!requestId) return undefined;
+    if (!requestId) {
+      return undefined;
+    }
     return {
       requestId,
       actions: APPROVAL_ACTIONS,
@@ -74,12 +75,11 @@ function resolveApprovalContext(
   }
 
   if (signal.sourceEventName === "guardian.question") {
-    const parsed = parseGuardianQuestionPayload(payload);
-    if (!parsed) return undefined;
-    const { mode } = resolveGuardianInstructionModeFromPayload(parsed);
-    if (mode !== "approval") return undefined;
-    const requestId = nonEmpty(parsed.requestId);
-    if (!requestId) return undefined;
+    const parsed = parseInteractiveApprovalPayload(payload);
+    if (!parsed) {
+      return undefined;
+    }
+    const requestId = parsed.requestId;
 
     // Extract tool context so channel adapters can render structured
     // approval cards without re-parsing contextPayload.
@@ -184,8 +184,12 @@ export class NotificationBroadcaster {
     // event fires immediately, before slower channel sends (e.g. Telegram 30s
     // timeout) can delay it past the macOS deep-link retry window.
     const orderedChannels = [...decision.selectedChannels].sort((a, b) => {
-      if (a === "vellum") return -1;
-      if (b === "vellum") return 1;
+      if (a === "vellum") {
+        return -1;
+      }
+      if (b === "vellum") {
+        return 1;
+      }
       return 0;
     });
 
@@ -552,7 +556,9 @@ export class NotificationBroadcaster {
 function resolveSourceConversationId(
   sourceContextId: string | undefined,
 ): string | undefined {
-  if (!sourceContextId) return undefined;
+  if (!sourceContextId) {
+    return undefined;
+  }
   try {
     return getConversation(sourceContextId) ? sourceContextId : undefined;
   } catch {

package/src/notifications/decision-engine.ts

@@ -47,8 +47,10 @@ import { createDecision } from "./decisions-store.js";
 import {
   buildGuardianRequestCodeInstruction,
   hasGuardianRequestCodeInstruction,
+  parseInteractiveApprovalPayload,
   resolveGuardianQuestionInstructionMode,
   stripConflictingGuardianRequestInstructions,
+  stripGuardianRequestCodeInstructions,
 } from "./guardian-question-mode.js";
 import { nonEmpty, readPayloadString } from "./notification-utils.js";
 import { getPreferenceSummary } from "./preference-summary.js";
@@ -143,6 +145,7 @@ function buildSystemPrompt(
     `  - Avoid meta-send phrasing (e.g. "I'd like to send a notification", "May I go ahead with that?"). Write the recipient-facing message directly.`,
     `  - Avoid intermediary-instruction phrasing like "consider telling the guardian", "ask the recipient to", or "the assistant should remind them". Rewrite it as final copy the recipient can act on directly.`,
     `  - For telegram: 1-2 concise sentences.`,
+    `  - For slack approval requests: the message renders inside an interactive card with Approve/Reject buttons. Describe only what needs approval — never include approval/reference codes, code-reply instructions, or directions to respond in another app.`,
     `- \`conversationSeedMessage\` is the opening message in the internal notification conversation and also the expanded detail shown in the home feed. It should be richer and more contextual than the popup body.`,
     `  - For vellum (desktop): use structured markdown for readability. Break content into bullet points, numbered lists, or short sections with **bold** labels. Avoid long unbroken paragraphs — scan-friendly formatting is preferred.`,
     `  - Never dump raw JSON. Include only human-readable context.`,
@@ -382,11 +385,19 @@ function validateDecisionOutput(
   availableChannels: NotificationChannel[],
   candidateSet?: ConversationCandidateSet,
 ): NotificationDecision | null {
-  if (typeof input.shouldNotify !== "boolean") return null;
-  if (typeof input.reasoningSummary !== "string") return null;
-  if (typeof input.dedupeKey !== "string") return null;
+  if (typeof input.shouldNotify !== "boolean") {
+    return null;
+  }
+  if (typeof input.reasoningSummary !== "string") {
+    return null;
+  }
+  if (typeof input.dedupeKey !== "string") {
+    return null;
+  }
 
-  if (!Array.isArray(input.selectedChannels)) return null;
+  if (!Array.isArray(input.selectedChannels)) {
+    return null;
+  }
   const validatedChannels = (input.selectedChannels as unknown[]).filter(
     (ch): ch is NotificationChannel =>
       typeof ch === "string" &&
@@ -482,7 +493,9 @@ export function validateConversationActions(
 ): Partial<Record<NotificationChannel, ConversationAction>> {
   const result: Partial<Record<NotificationChannel, ConversationAction>> = {};
 
-  if (!raw || typeof raw !== "object") return result;
+  if (!raw || typeof raw !== "object") {
+    return result;
+  }
 
   const actionsObj = raw as Record<string, unknown>;
   const channelSet = new Set(validChannels);
@@ -502,8 +515,12 @@ export function validateConversationActions(
   }
 
   for (const [ch, actionRaw] of Object.entries(actionsObj)) {
-    if (!channelSet.has(ch as NotificationChannel)) continue;
-    if (!actionRaw || typeof actionRaw !== "object") continue;
+    if (!channelSet.has(ch as NotificationChannel)) {
+      continue;
+    }
+    if (!actionRaw || typeof actionRaw !== "object") {
+      continue;
+    }
 
     const channel = ch as NotificationChannel;
     const action = actionRaw as Record<string, unknown>;
@@ -558,8 +575,9 @@ function ensureGuardianRequestCodeInCopy(
       requestCode,
       mode,
     );
-    if (hasGuardianRequestCodeInstruction(sanitized, requestCode, mode))
+    if (hasGuardianRequestCodeInstruction(sanitized, requestCode, mode)) {
       return sanitized;
+    }
     return sanitized.length > 0
       ? `${sanitized}\n\n${instruction}`
       : instruction;
@@ -577,36 +595,79 @@ function ensureGuardianRequestCodeInCopy(
   };
 }
 
+/**
+ * Remove request-code reply instructions from copy for a channel whose
+ * approval UI makes them redundant. Instruction-only fields keep their
+ * original text rather than becoming empty — downstream treats an empty
+ * body as missing copy.
+ */
+function stripGuardianRequestCodeInCopy(
+  copy: RenderedChannelCopy,
+  requestCode: string,
+): RenderedChannelCopy {
+  const strip = (text: string): string => {
+    const stripped = stripGuardianRequestCodeInstructions(text, requestCode);
+    return stripped.length > 0 ? stripped : text;
+  };
+
+  return {
+    ...copy,
+    body: strip(copy.body),
+    deliveryText: copy.deliveryText
+      ? strip(copy.deliveryText)
+      : copy.deliveryText,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? strip(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
+  };
+}
+
 /**
  * Guardian questions that share a conversation require explicit request-code
  * targeting. Enforce request-code instructions in rendered copy so guardians
  * can always disambiguate replies even when model copy omits them.
+ *
+ * Slack is the exception for approval-mode questions: the Slack adapter
+ * renders those as an interactive card with Approve/Reject buttons (see
+ * `resolveApprovalContext` in broadcaster.ts, gated on the same
+ * `parseInteractiveApprovalPayload`), so code-reply instructions are
+ * redundant noise there and are stripped instead of enforced in.
  */
 function enforceGuardianRequestCode(
   decision: NotificationDecision,
   signal: NotificationSignal,
 ): NotificationDecision {
-  if (signal.sourceEventName !== "guardian.question") return decision;
+  if (signal.sourceEventName !== "guardian.question") {
+    return decision;
+  }
   const rawCode = signal.contextPayload.requestCode;
-  if (typeof rawCode !== "string" || rawCode.trim().length === 0)
+  if (typeof rawCode !== "string" || rawCode.trim().length === 0) {
     return decision;
+  }
 
   const requestCode = rawCode.trim().toUpperCase();
   const modeResolution = resolveGuardianQuestionInstructionMode(
     signal.contextPayload,
   );
+  const slackRendersApprovalButtons =
+    parseInteractiveApprovalPayload(signal.contextPayload) != null;
   const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
     ...decision.renderedCopy,
   };
 
   for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
     const copy = nextCopy[channel];
-    if (!copy) continue;
-    nextCopy[channel] = ensureGuardianRequestCodeInCopy(
-      copy,
-      requestCode,
-      modeResolution.mode,
-    );
+    if (!copy) {
+      continue;
+    }
+    nextCopy[channel] =
+      channel === "slack" && slackRendersApprovalButtons
+        ? stripGuardianRequestCodeInCopy(copy, requestCode)
+        : ensureGuardianRequestCodeInCopy(
+            copy,
+            requestCode,
+            modeResolution.mode,
+          );
   }
 
   return {
@@ -624,14 +685,18 @@ function ensureSeedContentBlocks(
   decision: NotificationDecision,
   blocks: unknown[] | null | undefined,
 ): NotificationDecision {
-  if (!blocks) return decision;
+  if (!blocks) {
+    return decision;
+  }
 
   const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
     ...decision.renderedCopy,
   };
   for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
     const copy = nextCopy[channel];
-    if (!copy) continue;
+    if (!copy) {
+      continue;
+    }
     if (!copy.seedContentBlocks) {
       nextCopy[channel] = { ...copy, seedContentBlocks: blocks };
     }
@@ -651,7 +716,9 @@ function enforceToolApprovalSeedBlocks(
   decision: NotificationDecision,
   signal: NotificationSignal,
 ): NotificationDecision {
-  if (signal.sourceEventName !== "guardian.question") return decision;
+  if (signal.sourceEventName !== "guardian.question") {
+    return decision;
+  }
   return ensureSeedContentBlocks(
     decision,
     buildToolApprovalSeedContentBlocks(signal.contextPayload),
@@ -675,7 +742,9 @@ function enforceAccessRequestInstructions(
   decision: NotificationDecision,
   signal: NotificationSignal,
 ): NotificationDecision {
-  if (signal.sourceEventName !== "ingress.access_request") return decision;
+  if (signal.sourceEventName !== "ingress.access_request") {
+    return decision;
+  }
 
   const rawCode = signal.contextPayload.requestCode;
   const hasRequestCode =
@@ -691,7 +760,9 @@ function enforceAccessRequestInstructions(
 
     for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
       const copy = nextCopy[channel];
-      if (!copy) continue;
+      if (!copy) {
+        continue;
+      }
       nextCopy[channel] = ensureAccessRequestInstructionsInCopy(
         copy,
         requestCode,
@@ -704,7 +775,9 @@ function enforceAccessRequestInstructions(
 
     for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
       const copy = nextCopy[channel];
-      if (!copy) continue;
+      if (!copy) {
+        continue;
+      }
       nextCopy[channel] = ensureInviteFlowDirectiveInCopy(
         copy,
         inviteDirective,
@@ -755,7 +828,9 @@ function ensureInviteFlowDirectiveInCopy(
 ): RenderedChannelCopy {
   const ensureText = (text: string | undefined): string => {
     const base = typeof text === "string" ? text.trim() : "";
-    if (hasInviteFlowDirective(base)) return base;
+    if (hasInviteFlowDirective(base)) {
+      return base;
+    }
     return base.length > 0 ? `${base}\n\n${inviteDirective}` : inviteDirective;
   };
 
@@ -1138,15 +1213,21 @@ export function enforceRoutingIntent(
       // Preserve the decision's selected channels first, then add connected
       // channels until we reach two channels total.
       for (const ch of selectedConnected) {
-        if (seen.has(ch)) continue;
+        if (seen.has(ch)) {
+          continue;
+        }
         expanded.push(ch);
         seen.add(ch);
       }
       for (const ch of connectedChannels) {
-        if (seen.has(ch)) continue;
+        if (seen.has(ch)) {
+          continue;
+        }
         expanded.push(ch);
         seen.add(ch);
-        if (expanded.length >= 2) break;
+        if (expanded.length >= 2) {
+          break;
+        }
       }
 
       const enforced = { ...decision };
@@ -1184,15 +1265,20 @@ export function enforceGuardianCallConversationAffinity(
   decision: NotificationDecision,
   signal: NotificationSignal,
 ): NotificationDecision {
-  if (signal.sourceEventName !== "guardian.question") return decision;
+  if (signal.sourceEventName !== "guardian.question") {
+    return decision;
+  }
 
   const callSessionId = signal.contextPayload?.callSessionId;
-  if (typeof callSessionId !== "string" || callSessionId.trim().length === 0)
+  if (typeof callSessionId !== "string" || callSessionId.trim().length === 0) {
     return decision;
+  }
 
   // If an affinity hint already exists for vellum, the second+ dispatch
   // will be handled by enforceConversationAffinity — nothing to do here.
-  if (signal.conversationAffinityHint?.vellum) return decision;
+  if (signal.conversationAffinityHint?.vellum) {
+    return decision;
+  }
 
   const enforced = { ...decision };
   const conversationActions: Partial<
@@ -1226,13 +1312,17 @@ function enforceConversationAffinity(
   decision: NotificationDecision,
   affinityHint: Partial<Record<string, string>> | undefined,
 ): NotificationDecision {
-  if (!affinityHint) return decision;
+  if (!affinityHint) {
+    return decision;
+  }
 
   const entries = Object.entries(affinityHint).filter(
     ([, conversationId]) =>
       typeof conversationId === "string" && conversationId.length > 0,
   );
-  if (entries.length === 0) return decision;
+  if (entries.length === 0) {
+    return decision;
+  }
 
   const enforced = { ...decision };
   const conversationActions: Partial<