@vellumai/assistant 0.10.0 → 0.10.1-staging.1

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/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/deterministic-checks.ts

@@ -3,8 +3,13 @@
  *
  * These checks run after the decision engine produces a NotificationDecision
  * and before the broadcaster dispatches. They enforce hard invariants that
- * the LLM cannot override: channel availability, source-active suppression,
- * deduplication, and schema validity.
+ * the LLM cannot override: channel availability, deduplication, schema
+ * validity, and rendered-copy quality.
+ *
+ * Source-active suppression is also a hard invariant, but it depends only on
+ * the signal — not on the decision — so `emitNotificationSignal` runs it as a
+ * pre-decision gate, short-circuiting before the expensive LLM stage rather
+ * than discarding the decision after it. See `checkSourceActiveSuppression`.
  */
 
 import { and, eq } from "drizzle-orm";
@@ -52,17 +57,7 @@ export async function runDeterministicChecks(
     return schemaCheck;
   }
 
-  // Check 2: Source-active suppression
-  const sourceActiveCheck = checkSourceActiveSuppression(signal);
-  if (!sourceActiveCheck.passed) {
-    log.info(
-      { signalId: signal.signalId, reason: sourceActiveCheck.reason },
-      "Deterministic check failed: source active",
-    );
-    return sourceActiveCheck;
-  }
-
-  // Check 3: Channel availability
+  // Check 2: Channel availability
   const channelCheck = checkChannelAvailability(
     decision,
     context.connectedChannels,
@@ -75,7 +70,7 @@ export async function runDeterministicChecks(
     return channelCheck;
   }
 
-  // Check 4: Dedupe
+  // Check 3: Dedupe
   const dedupeCheck = checkDedupe(
     signal,
     decision,
@@ -89,7 +84,7 @@ export async function runDeterministicChecks(
     return dedupeCheck;
   }
 
-  // Check 5: Rendered copy quality (fail-closed)
+  // Check 4: Rendered copy quality (fail-closed)
   const copyCheck = checkRenderedCopyQuality(signal, decision);
   if (!copyCheck.passed) {
     log.info(
@@ -151,8 +146,16 @@ function checkDecisionSchema(decision: NotificationDecision): CheckResult {
 /**
  * If the user is already looking at the source context (visibleInSourceNow),
  * suppress the notification to avoid redundant alerts.
+ *
+ * This depends only on the signal, not on the decision, so the outcome is
+ * knowable before the decision engine runs. `emitNotificationSignal` calls it
+ * as a pre-decision gate to short-circuit statically-suppressed signals
+ * (e.g. trusted-contact `verification_sent`) before paying for an LLM
+ * inference whose result would be discarded. Exported for that caller.
  */
-function checkSourceActiveSuppression(signal: NotificationSignal): CheckResult {
+export function checkSourceActiveSuppression(
+  signal: NotificationSignal,
+): CheckResult {
   if (signal.attentionHints.visibleInSourceNow) {
     return {
       passed: false,

package/src/notifications/emit-signal.ts

@@ -27,6 +27,7 @@ import {
 import { enforceRoutingIntent, evaluateSignal } from "./decision-engine.js";
 import { updateDecision } from "./decisions-store.js";
 import {
+  checkSourceActiveSuppression,
   type DeterministicCheckContext,
   runDeterministicChecks,
 } from "./deterministic-checks.js";
@@ -209,7 +210,12 @@ export interface EmitSignalResult {
 
 /**
  * Emit a notification signal through the full pipeline:
- * createEvent -> evaluateSignal -> runDeterministicChecks -> dispatchDecision.
+ * createEvent -> (source-active pre-gate) -> evaluateSignal ->
+ * runDeterministicChecks -> dispatchDecision.
+ *
+ * Source-active suppression runs before the decision engine: it depends only
+ * on the signal, so a statically-suppressed signal short-circuits here without
+ * paying for an LLM inference whose result would be discarded downstream.
  *
  * Fire-and-forget safe by default: errors are caught and logged unless
  * `throwOnError` is enabled by the caller.
@@ -261,6 +267,28 @@ export async function emitNotificationSignal<TEventName extends string>(
       };
     }
 
+    // Step 1.5: Source-active pre-gate. visibleInSourceNow is a hard invariant
+    // the decision engine cannot override, and it depends only on the signal —
+    // so when it is set, the outcome is predetermined: suppress. Short-circuit
+    // before the (LLM-backed) decision stage so statically-suppressed signals
+    // (e.g. trusted-contact verification_sent) never incur an inference, a
+    // discarded decision row, or an LLM-dependent home-feed mirror. The event
+    // row persisted above preserves the lifecycle/audit trail.
+    const sourceActiveCheck = checkSourceActiveSuppression(signal);
+    if (!sourceActiveCheck.passed) {
+      log.info(
+        { signalId, reason: sourceActiveCheck.reason },
+        "Signal suppressed before decision stage (source-active)",
+      );
+      return {
+        signalId,
+        deduplicated: false,
+        dispatched: false,
+        reason: `Signal suppressed: ${sourceActiveCheck.reason}`,
+        deliveryResults: [],
+      };
+    }
+
     // Step 2: Evaluate the signal through the decision engine
     const connectedChannels = getConnectedChannels();
 

package/src/notifications/trusted-contact-payloads.ts

@@ -0,0 +1,70 @@
+/**
+ * Typed context payloads for the trusted-contact lifecycle notification signals.
+ *
+ * These `ingress.trusted_contact.*` signals are emitted from the canonical
+ * resolver (`approvals/guardian-request-resolvers.ts`), and the decision
+ * payload is read back by the notification copy-composer. A single zod schema
+ * is the source of truth for both sides, so the producer cannot drift from the
+ * consumer.
+ *
+ * Identity fields are nullable: producers populate them (using "" for an
+ * unknown id), but a payload read back off persisted JSON may legitimately
+ * carry a null/absent identity, and the copy-composer degrades per-field. Only
+ * `sourceChannel` and `decision` are strict — they gate routing and rendering.
+ *
+ * Shapes are zod schemas (single source of truth for runtime validation and
+ * TypeScript types), matching the `guardian.question` payload pattern.
+ * https://zod.dev/?id=basic-usage
+ */
+
+import { z } from "zod";
+
+import { NotificationSourceChannelSchema } from "./signal.js";
+
+/** Identity fields shared by every trusted-contact lifecycle payload. */
+const TrustedContactIdentitySchema = z.object({
+  sourceChannel: NotificationSourceChannelSchema,
+  requesterExternalUserId: z.string().nullable(),
+  requesterChatId: z.string().nullable(),
+  requesterDisplayName: z.string().nullable(),
+  decidedByDisplayName: z.string().nullable(),
+});
+
+/**
+ * Payload for `ingress.trusted_contact.guardian_decision` and
+ * `ingress.trusted_contact.denied` — the guardian's verdict on an access
+ * request. The deny path emits both events from one object; the approve path
+ * emits `guardian_decision` with `decision: "approved"` (identical shape).
+ */
+export const TrustedContactDecisionPayloadSchema =
+  TrustedContactIdentitySchema.extend({
+    decidedByExternalUserId: z.string().nullable(),
+    decision: z.enum(["approved", "denied"]),
+  });
+export type TrustedContactDecisionPayload = z.infer<
+  typeof TrustedContactDecisionPayloadSchema
+>;
+
+/**
+ * Payload for `ingress.trusted_contact.verification_sent` — the verification
+ * code was minted and delivered. Carries the session id; no `decision`.
+ */
+export const TrustedContactVerificationSentPayloadSchema =
+  TrustedContactIdentitySchema.extend({
+    verificationSessionId: z.string(),
+  });
+export type TrustedContactVerificationSentPayload = z.infer<
+  typeof TrustedContactVerificationSentPayloadSchema
+>;
+
+/**
+ * Parse an unknown context payload as a trusted-contact decision payload.
+ * Returns the typed payload on success, or `null` when the shape doesn't match
+ * — the copy-composer falls back to generic copy in that case.
+ */
+export function parseTrustedContactDecisionPayload(
+  payload: Record<string, unknown>,
+): TrustedContactDecisionPayload | null {
+  const result = TrustedContactDecisionPayloadSchema.safeParse(payload);
+  return result.success ? result.data : null;
+}

package/src/oauth/byo-connection.test.ts

@@ -113,6 +113,15 @@ mock.module("./oauth-store.js", () => ({
     if (opts?.account && conn.accountInfo !== opts.account) return undefined;
     return conn;
   },
+  getActiveConnections: (
+    service: string,
+    opts?: { clientId?: string; account?: string },
+  ) => {
+    const conn = mockConnections.get(service);
+    if (!conn) return [];
+    if (opts?.account && conn.accountInfo !== opts.account) return [];
+    return [conn];
+  },
   getConnection: (id: string) => {
     for (const conn of mockConnections.values()) {
       if (conn.id === id) return conn;