@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

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

@@ -7,18 +7,73 @@
  * 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`.
+ * The `[ui_surface, text]` block pair is described by {@link ApprovalCardBlockSchema}
+ * so the builder returns a schema-derived type rather than `unknown[]`: the card
+ * `data` composes the canonical {@link CardSurfaceDataSchema} and actions reuse
+ * the canonical {@link SurfaceActionSchema}. Actions use the
+ * `apr:<requestId>:<action>` callback format consumed by
+ * `surface-action-routes.ts` → `processGuardianDecision`.
  */
 
+import { z } from "zod";
+
+import {
+  type SurfaceAction,
+  SurfaceActionSchema,
+} from "../api/events/ui-surface-show.js";
+import {
+  type CardSurfaceData,
+  CardSurfaceDataSchema,
+} from "../daemon/message-types/surfaces.js";
+
+// ── Seed content block schema ─────────────────────────────────────────────────
+
+/**
+ * The interactive `ui_surface` card block clients render via
+ * `SurfaceRouter → CardSurface`. `data` is the canonical card surface data;
+ * `actions` reuse the canonical surface action schema.
+ */
+export const ApprovalCardSurfaceBlockSchema = z.object({
+  type: z.literal("ui_surface"),
+  surfaceId: z.string(),
+  surfaceType: z.literal("card"),
+  title: z.string(),
+  data: CardSurfaceDataSchema,
+  actions: z.array(SurfaceActionSchema).optional(),
+});
+
+/**
+ * The plain-text fallback block, flagged so the display projector
+ * (`renderHistoryContent`) keeps it in flat `.text` but omits it from the
+ * rendered `contentBlocks` — without it a surface-capable client would render
+ * the card AND a duplicate text line.
+ */
+export const ApprovalCardFallbackBlockSchema = z.object({
+  type: z.literal("text"),
+  text: z.string(),
+  _surfaceFallback: z.literal(true),
+});
+
+/** The `[ui_surface, text]` seed block pair produced for a guardian card. */
+export const ApprovalCardBlockSchema = z.discriminatedUnion("type", [
+  ApprovalCardSurfaceBlockSchema,
+  ApprovalCardFallbackBlockSchema,
+]);
+
+export type ApprovalCardSurfaceBlock = z.infer<
+  typeof ApprovalCardSurfaceBlockSchema
+>;
+export type ApprovalCardFallbackBlock = z.infer<
+  typeof ApprovalCardFallbackBlockSchema
+>;
+export type ApprovalCardBlock = z.infer<typeof ApprovalCardBlockSchema>;
+
 // ── 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"). */
+  /** 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;
@@ -40,10 +95,13 @@ export interface ApprovalCardParams {
  * 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.
+ * clients that support Surface rendering. The `text` block is the card's
+ * plain-text fallback — it feeds the model, search indexing, CLI display, and
+ * channel replies, which read it as ordinary text.
  */
-export function buildApprovalCardBlocks(params: ApprovalCardParams): unknown[] {
+export function buildApprovalCardBlocks(
+  params: ApprovalCardParams,
+): ApprovalCardBlock[] {
   const {
     surfaceIdPrefix,
     cardTitle,
@@ -55,7 +113,7 @@ export function buildApprovalCardBlocks(params: ApprovalCardParams): unknown[] {
     fallbackText,
   } = params;
 
-  const actions = requestId
+  const actions: SurfaceAction[] | undefined = requestId
     ? [
         {
           id: `apr:${requestId}:approve_once`,
@@ -70,23 +128,26 @@ export function buildApprovalCardBlocks(params: ApprovalCardParams): unknown[] {
       ]
     : undefined;
 
-  const surfaceBlock = {
-    type: "ui_surface" as const,
+  const data: CardSurfaceData = {
+    title: requesterName,
+    subtitle,
+    body,
+    metadata,
+  };
+
+  const surfaceBlock: ApprovalCardSurfaceBlock = {
+    type: "ui_surface",
     surfaceId: `${surfaceIdPrefix}-${requestId ?? "unknown"}`,
-    surfaceType: "card" as const,
+    surfaceType: "card",
     title: cardTitle,
-    data: {
-      title: requesterName,
-      subtitle,
-      body,
-      metadata,
-    },
+    data,
     ...(actions ? { actions } : {}),
   };
 
-  const textBlock = {
-    type: "text" as const,
+  const textBlock: ApprovalCardFallbackBlock = {
+    type: "text",
     text: fallbackText,
+    _surfaceFallback: true,
   };
 
   return [surfaceBlock, textBlock];

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

@@ -19,6 +19,7 @@ import {
   parseAccessRequestPayload,
 } from "./access-request-copy.js";
 import {
+  type ApprovalCardBlock,
   type ApprovalCardParams,
   buildApprovalCardBlocks,
 } from "./approval-card-builder.js";
@@ -285,7 +286,9 @@ export function resolveApprovalCardData(
 }
 
 /** Render resolved approval card data into Surface `[ui_surface, text]` blocks. */
-export function renderApprovalCardData(data: ApprovalCardData): unknown[] {
+export function renderApprovalCardData(
+  data: ApprovalCardData,
+): ApprovalCardBlock[] {
   return buildApprovalCardBlocks(data.card);
 }
 
@@ -300,7 +303,7 @@ export function renderApprovalCardData(data: ApprovalCardData): unknown[] {
  */
 export function buildAccessRequestSeedContentBlocks(
   payload: Record<string, unknown>,
-): unknown[] {
+): ApprovalCardBlock[] {
   return renderApprovalCardData({
     kind: "access_request",
     card: resolveAccessRequestCard(payload),
@@ -318,13 +321,13 @@ export function buildAccessRequestSeedContentBlocks(
  */
 export function buildToolApprovalSeedContentBlocks(
   payload: GuardianQuestionPayload,
-): unknown[] | null;
+): ApprovalCardBlock[] | null;
 export function buildToolApprovalSeedContentBlocks(
   payload: Record<string, unknown>,
-): unknown[] | null;
+): ApprovalCardBlock[] | null;
 export function buildToolApprovalSeedContentBlocks(
   payload: GuardianQuestionPayload | Record<string, unknown>,
-): unknown[] | null {
+): ApprovalCardBlock[] | null {
   const data = resolveApprovalCardData(
     "guardian.question",
     payload as Record<string, unknown>,

package/src/notifications/broadcaster.ts

@@ -11,6 +11,7 @@
 
 import { v4 as uuid } from "uuid";
 
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
 import { getConversation } from "../memory/conversation-crud.js";
 import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
@@ -171,7 +172,13 @@ export class NotificationBroadcaster {
     decision: NotificationDecision,
     options?: BroadcastDecisionOptions,
   ): Promise<NotificationDeliveryResult[]> {
-    const destinations = resolveDestinations(decision.selectedChannels);
+    // Pull the guardian list once so the resolver stays pure. A null list
+    // (gateway unreachable) falls back to the local contacts read.
+    const guardians = await getGuardianDelivery();
+    const destinations = resolveDestinations(
+      decision.selectedChannels,
+      guardians,
+    );
 
     // Ensure vellum is processed first so the notification_conversation_created
     // event fires immediately, before slower channel sends (e.g. Telegram 30s

package/src/notifications/canonical-delivery-recorder.ts

@@ -91,11 +91,12 @@ export function recordApprovalCardDelivery(
  * that row's id as `vellumDeliveryId` and it is reused (only its status applied)
  * — otherwise the vellum row is created here from the result.
  *
- * The pipeline result carries the delivered address directly: a `vellum` result
- * carries a `conversationId`; channel results carry the chat (`destination`) and
- * channel-native id (`messageId`). A blank `destination` is recorded as unknown
- * rather than persisting the literal channel name as a chat id. Status is
- * diagnostic — the read paths key off addressing, not status.
+ * Every result records the internal `conversationId` the card is shown in, so a
+ * conversation's pending cards can be found uniformly regardless of channel.
+ * Channel results additionally carry the chat (`destination`) and channel-native
+ * id (`messageId`) used to match inbound replies/reactions; a blank `destination`
+ * is recorded as unknown rather than persisting the literal channel name as a
+ * chat id. Status is diagnostic — the read paths key off addressing, not status.
  *
  * Returns the vellum delivery id (passed in, or created here) so a caller can
  * record its own "pipeline produced no vellum delivery" fallback.
@@ -123,6 +124,7 @@ export function recordGuardianRequestDeliveries(params: {
       deliveryId = recordApprovalCardDelivery({
         requestId,
         channel: result.channel,
+        conversationId: result.conversationId,
         chatId: result.destination.length > 0 ? result.destination : undefined,
         messageId: result.messageId,
       })?.id;

package/src/notifications/conversation-candidates.ts

@@ -10,11 +10,11 @@
  * needs for a routing decision, not full conversation contents.
  */
 
-import { and, count, desc, eq, inArray, isNotNull } from "drizzle-orm";
+import { and, desc, eq, isNotNull } from "drizzle-orm";
 
+import { listPendingRequestsByConversationScope } from "../memory/canonical-guardian-store.js";
 import { getDb } from "../memory/db-connection.js";
 import {
-  channelGuardianApprovalRequests,
   conversations,
   notificationDecisions,
   notificationDeliveries,
@@ -169,74 +169,39 @@ function buildCandidatesForChannel(
     if (candidates.length >= MAX_CANDIDATES_PER_CHANNEL) break;
   }
 
-  // Batch-enrich all candidates with guardian context in a single query
-  if (candidates.length > 0) {
-    const pendingCounts = batchCountPendingByConversation(
-      candidates.map((c) => c.conversationId),
-    );
-    for (const candidate of candidates) {
-      const pendingCount = pendingCounts.get(candidate.conversationId) ?? 0;
+  // Enrich each candidate with its count of pending guardian requests. The
+  // canonical store owns the addressing convention and counts by conversation
+  // scope: the request's source conversation plus any conversation its card was
+  // delivered to (e.g. an access request whose synthetic source id differs from
+  // the in-app card's destination conversation).
+  //
+  // Best-effort per candidate: guardian context is supplementary, so a lookup
+  // failure degrades that candidate to "no context" (logged) rather than
+  // propagating to the per-channel catch in `buildConversationCandidates`,
+  // which would discard the channel's whole candidate set.
+  for (const candidate of candidates) {
+    try {
+      const pendingCount = listPendingRequestsByConversationScope(
+        candidate.conversationId,
+        candidate.channel,
+      ).length;
       if (pendingCount > 0) {
         candidate.guardianContext = {
           pendingUnresolvedRequestCount: pendingCount,
         };
       }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.warn(
+        { err: errMsg, conversationId: candidate.conversationId },
+        "Failed to enrich candidate with guardian context",
+      );
     }
   }
 
   return candidates;
 }
 
-// -- Guardian context enrichment ----------------------------------------------
-
-/**
- * Batch-count pending guardian approval requests for multiple conversations
- * in a single query. Returns a map from conversationId to pending count
- * (only entries with count > 0 are included).
- */
-function batchCountPendingByConversation(
-  conversationIds: string[],
-): Map<string, number> {
-  const result = new Map<string, number>();
-  if (conversationIds.length === 0) return result;
-
-  try {
-    const db = getDb();
-
-    const rows = db
-      .select({
-        conversationId: channelGuardianApprovalRequests.conversationId,
-        count: count(),
-      })
-      .from(channelGuardianApprovalRequests)
-      .where(
-        and(
-          inArray(
-            channelGuardianApprovalRequests.conversationId,
-            conversationIds,
-          ),
-          eq(channelGuardianApprovalRequests.status, "pending"),
-        ),
-      )
-      .groupBy(channelGuardianApprovalRequests.conversationId)
-      .all();
-
-    for (const row of rows) {
-      if (row.count > 0) {
-        result.set(row.conversationId, row.count);
-      }
-    }
-  } catch (err) {
-    const errMsg = err instanceof Error ? err.message : String(err);
-    log.warn(
-      { err: errMsg },
-      "Failed to batch-query guardian context for candidates",
-    );
-  }
-
-  return result;
-}
-
 // -- Prompt serialization -----------------------------------------------------
 
 /**

package/src/notifications/copy-composer.ts

@@ -29,6 +29,7 @@ import type {
   NotificationSignal,
   NotificationSourceEventName,
 } from "./signal.js";
+import { parseTrustedContactDecisionPayload } from "./trusted-contact-payloads.js";
 import type { NotificationChannel, RenderedChannelCopy } from "./types.js";
 
 type CopyTemplate = (payload: Record<string, unknown>) => RenderedChannelCopy;
@@ -52,6 +53,35 @@ export function deriveTitle(body: string): string {
     : candidate.trim();
 }
 
+/**
+ * Build a display label for a trusted-contact actor (requester or decider),
+ * preferring the display name, then a Slack `<@id>` mention for raw Slack user
+ * IDs, then the raw id, then a generic fallback. The result is sanitized for
+ * safe inclusion in notification copy.
+ */
+function formatTrustedContactActor(
+  displayName: string | null | undefined,
+  externalUserId: string | null | undefined,
+  sourceChannel: string | null | undefined,
+  fallback: string,
+): string {
+  const name =
+    typeof displayName === "string" && displayName.length > 0
+      ? displayName
+      : undefined;
+  const slackMention =
+    sourceChannel === "slack" &&
+    typeof externalUserId === "string" &&
+    /^U[A-Z0-9]+$/i.test(externalUserId)
+      ? `<@${externalUserId}>`
+      : undefined;
+  const rawId =
+    typeof externalUserId === "string" && externalUserId.length > 0
+      ? externalUserId
+      : undefined;
+  return sanitizeIdentityField(name ?? slackMention ?? rawId ?? fallback);
+}
+
 // Templates keyed by dot-separated sourceEventName strings matching producers.
 const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
   "schedule.notify": (payload) => ({
@@ -168,53 +198,20 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
   },
 
   "ingress.trusted_contact.guardian_decision": (payload) => {
-    const decision = str(payload.decision, "decided on");
-    const sourceChannel =
-      typeof payload.sourceChannel === "string"
-        ? payload.sourceChannel
-        : undefined;
-
-    const requesterDisplayName =
-      typeof payload.requesterDisplayName === "string" &&
-      payload.requesterDisplayName.length > 0
-        ? payload.requesterDisplayName
-        : undefined;
-    const requesterExternalUserId =
-      typeof payload.requesterExternalUserId === "string" &&
-      payload.requesterExternalUserId.length > 0
-        ? payload.requesterExternalUserId
-        : undefined;
-    const requesterLabel = sanitizeIdentityField(
-      requesterDisplayName ??
-        (sourceChannel === "slack" &&
-        requesterExternalUserId &&
-        /^U[A-Z0-9]+$/i.test(requesterExternalUserId)
-          ? `<@${requesterExternalUserId}>`
-          : requesterExternalUserId) ??
-        "Someone",
+    const parsed = parseTrustedContactDecisionPayload(payload);
+    const requesterLabel = formatTrustedContactActor(
+      parsed?.requesterDisplayName,
+      parsed?.requesterExternalUserId,
+      parsed?.sourceChannel,
+      "Someone",
     );
-
-    const decidedByDisplayName =
-      typeof payload.decidedByDisplayName === "string" &&
-      payload.decidedByDisplayName.length > 0
-        ? payload.decidedByDisplayName
-        : undefined;
-    const decidedByExternalUserId =
-      typeof payload.decidedByExternalUserId === "string" &&
-      payload.decidedByExternalUserId.length > 0
-        ? payload.decidedByExternalUserId
-        : undefined;
-    const decidedByLabel = sanitizeIdentityField(
-      decidedByDisplayName ??
-        (sourceChannel === "slack" &&
-        decidedByExternalUserId &&
-        /^U[A-Z0-9]+$/i.test(decidedByExternalUserId)
-          ? `<@${decidedByExternalUserId}>`
-          : decidedByExternalUserId) ??
-        "a guardian",
+    const decidedByLabel = formatTrustedContactActor(
+      parsed?.decidedByDisplayName,
+      parsed?.decidedByExternalUserId,
+      parsed?.sourceChannel,
+      "a guardian",
     );
-
-    const verb = decision === "approved" ? "approved" : "denied";
+    const verb = parsed?.decision === "approved" ? "approved" : "denied";
     return {
       title: "Trusted Contact Decision",
       body: `${requesterLabel}'s access request has been ${verb} by ${decidedByLabel}.`,
@@ -222,29 +219,12 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
   },
 
   "ingress.trusted_contact.denied": (payload) => {
-    const sourceChannel =
-      typeof payload.sourceChannel === "string"
-        ? payload.sourceChannel
-        : undefined;
-
-    const requesterDisplayName =
-      typeof payload.requesterDisplayName === "string" &&
-      payload.requesterDisplayName.length > 0
-        ? payload.requesterDisplayName
-        : undefined;
-    const requesterExternalUserId =
-      typeof payload.requesterExternalUserId === "string" &&
-      payload.requesterExternalUserId.length > 0
-        ? payload.requesterExternalUserId
-        : undefined;
-    const requesterLabel = sanitizeIdentityField(
-      requesterDisplayName ??
-        (sourceChannel === "slack" &&
-        requesterExternalUserId &&
-        /^U[A-Z0-9]+$/i.test(requesterExternalUserId)
-          ? `<@${requesterExternalUserId}>`
-          : requesterExternalUserId) ??
-        "Someone",
+    const parsed = parseTrustedContactDecisionPayload(payload);
+    const requesterLabel = formatTrustedContactActor(
+      parsed?.requesterDisplayName,
+      parsed?.requesterExternalUserId,
+      parsed?.sourceChannel,
+      "Someone",
     );
 
     return {

package/src/notifications/decision-engine.ts

@@ -12,7 +12,11 @@
 import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
-import { listGuardianChannels } from "../contacts/contact-store.js";
+import { findContactInfoById } from "../contacts/contact-store.js";
+import {
+  anyGuardian,
+  getGuardianDelivery,
+} from "../contacts/guardian-delivery-reader.js";
 import { buildCoreIdentityContext } from "../prompts/system-prompt.js";
 import {
   createTimeout,
@@ -963,15 +967,19 @@ async function classifyWithLLM(
     ? truncate(rawIdentityContext, MAX_IDENTITY_CONTEXT_CHARS, "\n…[truncated]")
     : undefined;
 
-  // Resolve guardian contact notes for recipient context. Use the channel-
-  // agnostic guardian lookup so notes are available even when the only
-  // deliverable channel is "vellum" (which has no contact channel type).
+  // Resolve guardian contact notes for recipient context. The guardian's
+  // identity (ACL) comes from the gateway pull, channel-agnostic so notes are
+  // available even when the only deliverable channel is "vellum". Notes (INFO)
+  // stay local and are joined by contactId.
   let recipientNotes: string | undefined;
   try {
-    const guardianResult = listGuardianChannels();
-    if (guardianResult?.contact.notes) {
+    const guardian = anyGuardian((await getGuardianDelivery()) ?? []);
+    const notes = guardian
+      ? findContactInfoById(guardian.contactId)?.notes
+      : undefined;
+    if (notes) {
       recipientNotes = truncate(
-        guardianResult.contact.notes,
+        notes,
         MAX_IDENTITY_CONTEXT_CHARS,
         "\n…[truncated]",
       );