@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/notifications/broadcaster.ts

@@ -12,7 +12,9 @@
 import { v4 as uuid } from "uuid";
 
 import { getConversation } from "../memory/conversation-crud.js";
+import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
+import { buildAccessRequestContractText } from "./access-request-copy.js";
 import { isGuardianSensitiveEvent } from "./adapters/macos.js";
 import { pairDeliveryWithConversation } from "./conversation-pairing.js";
 import { composeFallbackCopy } from "./copy-composer.js";
@@ -22,6 +24,11 @@ import {
   updateDeliveryStatus,
 } from "./deliveries-store.js";
 import { resolveDestinations } from "./destination-resolver.js";
+import {
+  parseGuardianQuestionPayload,
+  resolveGuardianInstructionModeFromPayload,
+} from "./guardian-question-mode.js";
+import { nonEmpty } from "./notification-utils.js";
 import type { NotificationSignal } from "./signal.js";
 import type {
   ChannelAdapter,
@@ -35,6 +42,71 @@ import type {
 
 const log = getLogger("notif-broadcaster");
 
+const APPROVAL_ACTIONS: ApprovalUIMetadata["actions"] = [
+  { id: "approve_once", label: "Approve once" },
+  { id: "reject", label: "Reject" },
+];
+
+/**
+ * Resolve structured approval context from a notification signal.
+ * Returns `undefined` when the signal does not represent an approval flow.
+ */
+function resolveApprovalContext(
+  signal: NotificationSignal,
+): ApprovalUIMetadata | undefined {
+  const payload = signal.contextPayload;
+  if (!payload) return undefined;
+
+  if (signal.sourceEventName === "ingress.access_request") {
+    const requestId = nonEmpty(
+      typeof payload.requestId === "string" ? payload.requestId : undefined,
+    );
+    if (!requestId) return undefined;
+    return {
+      requestId,
+      actions: APPROVAL_ACTIONS,
+      plainTextFallback: buildAccessRequestContractText(payload),
+    };
+  }
+
+  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;
+
+    // Extract tool context so channel adapters can render structured
+    // approval cards without re-parsing contextPayload.
+    let toolName: string | undefined;
+    if (
+      parsed.requestKind === "tool_approval" ||
+      parsed.requestKind === "tool_grant_request"
+    ) {
+      toolName = nonEmpty(parsed.toolName);
+    } else if (parsed.requestKind === "pending_question") {
+      toolName = nonEmpty(parsed.toolName);
+    }
+
+    return {
+      requestId,
+      actions: APPROVAL_ACTIONS,
+      plainTextFallback: `Reply "${parsed.requestCode?.toUpperCase() ?? requestId} approve" or "${parsed.requestCode?.toUpperCase() ?? requestId} reject"`,
+      permissionDetails: toolName
+        ? {
+            toolName,
+            riskLevel: "medium",
+            toolInput: {},
+            requesterIdentifier: nonEmpty(parsed.requesterIdentifier),
+          }
+        : undefined,
+    };
+  }
+
+  return undefined;
+}
+
 /** Callback invoked immediately when a vellum notification conversation is created. */
 export interface ConversationCreatedInfo {
   conversationId: string;
@@ -108,6 +180,7 @@ export class NotificationBroadcaster {
       Record<NotificationChannel, RenderedChannelCopy>
     > | null = null;
 
+    const approvalContext = resolveApprovalContext(signal);
     const results: NotificationDeliveryResult[] = [];
 
     for (const channel of orderedChannels) {
@@ -337,6 +410,7 @@ export class NotificationBroadcaster {
         deepLinkTarget,
         contextPayload: signal.contextPayload,
         urgency: signal.attentionHints.urgency,
+        approvalContext,
       };
 
       // Compute conversation decision audit fields for the delivery record

package/src/notifications/conversation-pairing.ts

@@ -146,12 +146,14 @@ export async function pairDeliveryWithConversation(
       signal.conversationMetadata?.conversationType ??
       (strategy === "start_new_conversation" ? "standard" : "background");
 
-    // Prefer model-provided conversationSeedMessage when present and sane;
-    // fall back to the runtime composer which adapts verbosity to the
-    // delivery surface (vellum/macos = richer, telegram = compact).
-    const messageContent = isConversationSeedSane(copy.conversationSeedMessage)
-      ? copy.conversationSeedMessage
-      : composeConversationSeed(signal, channel, copy);
+    // Structured content blocks take precedence — they enable Surface-based
+    // rendering in the web/macOS/iOS apps (e.g. a card widget instead of
+    // plain text). Falls back to model-provided seed or runtime composer.
+    const messageContent = copy.seedContentBlocks
+      ? JSON.stringify(copy.seedContentBlocks)
+      : isConversationSeedSane(copy.conversationSeedMessage)
+        ? copy.conversationSeedMessage
+        : composeConversationSeed(signal, channel, copy);
 
     // Attempt to reuse an existing conversation when the model requests it
     if (conversationAction?.action === "reuse_existing") {

package/src/notifications/copy-composer.ts

@@ -11,16 +11,24 @@
 
 import {
   buildAccessRequestContractText,
-  sanitizeIdentityField,
+  buildAccessRequestSeedContentBlocks,
 } from "./access-request-copy.js";
 import {
   buildGuardianRequestCodeInstruction,
+  parseGuardianQuestionPayload,
+  resolveGuardianInstructionModeFromPayload,
   resolveGuardianQuestionInstructionMode,
 } from "./guardian-question-mode.js";
+import {
+  nonEmpty,
+  readPayloadString,
+  sanitizeIdentityField,
+} from "./notification-utils.js";
 import type {
   NotificationSignal,
   NotificationSourceEventName,
 } from "./signal.js";
+import { buildToolApprovalSeedContentBlocks } from "./tool-approval-copy.js";
 import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;
@@ -30,26 +38,6 @@ function str(value: unknown, fallback: string): string {
   return fallback;
 }
 
-export function nonEmpty(value: string | undefined): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-/**
- * Safely read a string property from an unknown-typed payload object.
- * Returns `undefined` when the payload is falsy, not an object, or the
- * key does not hold a string value.
- */
-export function readPayloadString(
-  payload: unknown,
-  key: string,
-): string | undefined {
-  if (!payload || typeof payload !== "object") return undefined;
-  const value = (payload as Record<string, unknown>)[key];
-  return typeof value === "string" ? value : undefined;
-}
-
 /**
  * Derive a short notification title from a message body. Trims to the
  * first sentence terminator when present, then caps the result at
@@ -76,25 +64,41 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
       payload.questionText,
       "A guardian question needs your attention",
     );
-    const requestCode = nonEmpty(
-      typeof payload.requestCode === "string" ? payload.requestCode : undefined,
-    );
+
+    // Parse once with Zod and reuse the typed payload downstream.
+    const parsed = parseGuardianQuestionPayload(payload);
 
     // For tool_grant_request, the questionText already includes requester name + input summary.
     // Use it directly as the conversation seed to avoid LLM-generated filler.
-    const isToolGrant = payload.requestKind === "tool_grant_request";
+    const isToolGrant = parsed?.requestKind === "tool_grant_request";
     const conversationSeedMessage = isToolGrant ? question : undefined;
 
+    const seedContentBlocks =
+      (parsed
+        ? buildToolApprovalSeedContentBlocks(parsed)
+        : buildToolApprovalSeedContentBlocks(payload)) ?? undefined;
+
+    const requestCode = parsed
+      ? nonEmpty(parsed.requestCode)
+      : nonEmpty(
+          typeof payload.requestCode === "string"
+            ? payload.requestCode
+            : undefined,
+        );
+
     if (!requestCode) {
       return {
         title: "Guardian Question",
         body: question,
         conversationSeedMessage,
+        seedContentBlocks,
       };
     }
 
     const normalizedCode = requestCode.toUpperCase();
-    const modeResolution = resolveGuardianQuestionInstructionMode(payload);
+    const modeResolution = parsed
+      ? resolveGuardianInstructionModeFromPayload(parsed)
+      : resolveGuardianQuestionInstructionMode(payload);
     const instruction = buildGuardianRequestCodeInstruction(
       normalizedCode,
       modeResolution.mode,
@@ -103,6 +107,7 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
       title: "Guardian Question",
       body: `${question}\n\n${instruction}`,
       conversationSeedMessage,
+      seedContentBlocks,
     };
   },
 
@@ -118,6 +123,7 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
   "ingress.access_request": (payload) => ({
     title: "Access Request",
     body: buildAccessRequestContractText(payload),
+    seedContentBlocks: buildAccessRequestSeedContentBlocks(payload),
   }),
 
   "ingress.access_request.callback_handoff": (payload) => {

package/src/notifications/decision-engine.ts

@@ -26,6 +26,7 @@ import { truncate } from "../util/truncate.js";
 import {
   buildAccessRequestContractText,
   buildAccessRequestInviteDirective,
+  buildAccessRequestSeedContentBlocks,
   hasAccessRequestInstructions,
   hasInviteFlowDirective,
 } from "./access-request-copy.js";
@@ -34,12 +35,7 @@ import {
   type ConversationCandidateSet,
   serializeCandidatesForPrompt,
 } from "./conversation-candidates.js";
-import {
-  composeFallbackCopy,
-  deriveTitle,
-  nonEmpty,
-  readPayloadString,
-} from "./copy-composer.js";
+import { composeFallbackCopy, deriveTitle } from "./copy-composer.js";
 import { createDecision } from "./decisions-store.js";
 import {
   buildGuardianRequestCodeInstruction,
@@ -47,8 +43,10 @@ import {
   resolveGuardianQuestionInstructionMode,
   stripConflictingGuardianRequestInstructions,
 } from "./guardian-question-mode.js";
+import { nonEmpty, readPayloadString } from "./notification-utils.js";
 import { getPreferenceSummary } from "./preference-summary.js";
 import type { NotificationSignal, RoutingIntent } from "./signal.js";
+import { buildToolApprovalSeedContentBlocks } from "./tool-approval-copy.js";
 import type {
   ConversationAction,
   NotificationChannel,
@@ -611,6 +609,49 @@ function enforceGuardianRequestCode(
   };
 }
 
+/**
+ * Inject seedContentBlocks into every channel's copy when not already present.
+ * Used by both tool-approval and access-request guards to ensure Surface cards
+ * render on all decision paths (LLM, assistant_tool, fallback).
+ */
+function ensureSeedContentBlocks(
+  decision: NotificationDecision,
+  blocks: unknown[] | null | undefined,
+): NotificationDecision {
+  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.seedContentBlocks) {
+      nextCopy[channel] = { ...copy, seedContentBlocks: blocks };
+    }
+  }
+
+  return {
+    ...decision,
+    renderedCopy: nextCopy,
+  };
+}
+
+/**
+ * Tool-approval and tool-grant notifications need a Surface card with
+ * Approve/Reject buttons on all decision paths.
+ */
+function enforceToolApprovalSeedBlocks(
+  decision: NotificationDecision,
+  signal: NotificationSignal,
+): NotificationDecision {
+  if (signal.sourceEventName !== "guardian.question") return decision;
+  return ensureSeedContentBlocks(
+    decision,
+    buildToolApprovalSeedContentBlocks(signal.contextPayload),
+  );
+}
+
 /**
  * Access-request notifications require deterministic instruction elements:
  * - Request-code approve/reject directive (when requestCode is present)
@@ -665,10 +706,18 @@ function enforceAccessRequestInstructions(
     }
   }
 
-  return {
+  let result: NotificationDecision = {
     ...decision,
     renderedCopy: nextCopy,
   };
+
+  // Ensure seedContentBlocks on all paths (LLM, assistant_tool, fallback).
+  result = ensureSeedContentBlocks(
+    result,
+    buildAccessRequestSeedContentBlocks(signal.contextPayload),
+  );
+
+  return result;
 }
 
 function ensureAccessRequestInstructionsInCopy(
@@ -833,6 +882,7 @@ export async function evaluateSignal(
       ...(deepLinkTarget ? { deepLinkTarget } : {}),
     };
     decision = enforceGuardianRequestCode(decision, signal);
+    decision = enforceToolApprovalSeedBlocks(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
     decision = enforceGuardianCallConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
@@ -850,6 +900,7 @@ export async function evaluateSignal(
     );
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
+    decision = enforceToolApprovalSeedBlocks(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
     decision = enforceGuardianCallConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
@@ -879,6 +930,7 @@ export async function evaluateSignal(
   }
 
   decision = enforceGuardianRequestCode(decision, signal);
+  decision = enforceToolApprovalSeedBlocks(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
   decision = enforceGuardianCallConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(