@vellumai/assistant 0.5.7 → 0.5.9

package/src/memory/retriever.ts

@@ -29,7 +29,6 @@ import {
   IDENTITY_KINDS,
   PREFERENCE_KINDS,
 } from "./search/formatting.js";
-import { recencySearch } from "./search/lexical.js";
 import { isQdrantConnectionError, semanticSearch } from "./search/semantic.js";
 import { applyStaleDemotion, computeStaleness } from "./search/staleness.js";
 import {
@@ -139,7 +138,7 @@ function buildDegradationStatus(
   return {
     semanticUnavailable: true,
     reason,
-    fallbackSources: ["recency"],
+    fallbackSources: [],
   };
 }
 
@@ -243,13 +242,12 @@ async function generateQueryEmbedding(
  *   1. Build query text (caller provides via buildMemoryQuery)
  *   2. Generate dense + sparse embeddings
  *   3. Hybrid search on Qdrant (dense + sparse RRF fusion)
- *   4. Supplement with recency search (conversation-scoped, DB only)
- *   5. Merge + deduplicate results
- *   6. Classify tiers (score > 0.8 → tier 1, > 0.6 → tier 2)
- *   7. Enrich item candidates with metadata for staleness
- *   8. Compute staleness per item
- *   9. Demote very_stale tier 1 → tier 2
- *  10. Build two-layer XML injection with budget allocation
+ *   4. Deduplicate results
+ *   5. Classify tiers (score > 0.6 → tier 1, > 0.4 → tier 2)
+ *   6. Enrich item candidates with metadata for staleness
+ *   7. Compute staleness per item
+ *   8. Demote very_stale tier 1 → tier 2
+ *   9. Build two-layer XML injection with budget allocation
  */
 export async function buildMemoryRecall(
   query: string,
@@ -327,21 +325,15 @@ export async function buildMemoryRecall(
       if (isQdrantConnectionError(err)) {
         log.warn({ err }, "Qdrant unavailable — hybrid search disabled");
       } else {
-        log.warn({ err }, "Hybrid search failed, continuing with recency only");
+        log.warn({ err }, "Hybrid search failed");
       }
     }
   }
   const hybridSearchMs = Date.now() - hybridSearchStart;
 
-  // ── Step 4: Recency supplement (DB only, conversation-scoped) ───
-  const recencyLimit = 5;
-  const recencyCandidates = conversationId
-    ? recencySearch(conversationId, recencyLimit, excludeMessageIds, scopeIds)
-    : [];
-
-  // ── Step 5: Merge and deduplicate ──────────────────────────────
+  // ── Step 4: Deduplicate ────────────────────────────────────────
   const candidateMap = new Map<string, Candidate>();
-  for (const c of [...hybridCandidates, ...recencyCandidates]) {
+  for (const c of [...hybridCandidates]) {
     const existing = candidateMap.get(c.key);
     if (!existing) {
       candidateMap.set(c.key, { ...c });
@@ -356,8 +348,7 @@ export async function buildMemoryRecall(
       existing.text = c.text;
     }
     // Propagate metadata that the first source may lack (e.g. legacy
-    // Qdrant points missing conversation_id / message_id). The recency
-    // source always has these from the DB, so merging fills the gap.
+    // Qdrant points missing conversation_id / message_id).
     if (c.conversationId && !existing.conversationId) {
       existing.conversationId = c.conversationId;
     }
@@ -366,7 +357,7 @@ export async function buildMemoryRecall(
     }
   }
 
-  // ── Step 5b: Filter out current-conversation segments still in context ──
+  // ── Step 4b: Filter out current-conversation segments still in context ──
   // Segments whose source message is still in the conversation's context
   // window are redundant (already visible to the model). However, segments
   // from messages that were removed by context compaction should be kept —
@@ -443,39 +434,26 @@ export async function buildMemoryRecall(
   // Compute RRF-style final scores for the merged candidates
   const allCandidates = [...candidateMap.values()];
   for (const c of allCandidates) {
-    // Simple weighted combination — hybrid search already applies RRF fusion
-    // at the Qdrant level; here we combine the fused semantic score with recency.
-    c.finalScore = c.semantic * 0.7 + c.recency * 0.2 + c.confidence * 0.1;
+    // Multiplicative scoring: importance, confidence, and recency amplify semantic
+    // relevance but can't substitute for it. An irrelevant item (semantic ≈ 0)
+    // stays low regardless of metadata. Multiplier range: 0.4 (all zero) to 1.0.
+    const metadataMultiplier =
+      0.4 + c.importance * 0.25 + c.confidence * 0.15 + c.recency * 0.2;
+    c.finalScore = c.semantic * metadataMultiplier;
   }
   allCandidates.sort((a, b) => b.finalScore - a.finalScore);
 
-  // ── Step 6: Tier classification ─────────────────────────────────
-  // Recency-only candidates (semantic=0) can never reach the tier 2 threshold
-  // (>0.6) since their max finalScore is 0.3. Promote them directly to tier 2
-  // so recent conversation context is preserved even without semantic signal.
-  const recencyOnlyKeys = new Set(
-    allCandidates
-      .filter((c) => c.semantic === 0 && c.recency > 0)
-      .map((c) => c.key),
-  );
+  // ── Step 5: Tier classification ─────────────────────────────────
   const tiered = classifyTiers(allCandidates);
-  if (recencyOnlyKeys.size > 0) {
-    const alreadyTiered = new Set(tiered.map((c) => c.key));
-    for (const c of allCandidates) {
-      if (recencyOnlyKeys.has(c.key) && !alreadyTiered.has(c.key)) {
-        tiered.push({ ...c, tier: 2 });
-      }
-    }
-  }
 
-  // ── Step 6b: Enrich candidates with source labels ──────────────
+  // ── Step 5b: Enrich candidates with source labels ──────────────
   enrichSourceLabels(tiered);
 
-  // ── Step 7: Enrich with item metadata for staleness ─────────────
+  // ── Step 6: Enrich with item metadata for staleness ─────────────
   const itemIds = tiered.filter((c) => c.type === "item").map((c) => c.id);
   const itemMetadataMap = enrichItemMetadata(itemIds);
 
-  // ── Step 8: Compute staleness per item ──────────────────────────
+  // ── Step 7: Compute staleness per item ──────────────────────────
   const now = Date.now();
   for (const c of tiered) {
     if (c.type !== "item") continue;
@@ -492,10 +470,10 @@ export async function buildMemoryRecall(
     c.staleness = level;
   }
 
-  // ── Step 9: Demote very_stale tier 1 → tier 2 ──────────────────
+  // ── Step 8: Demote very_stale tier 1 → tier 2 ──────────────────
   const afterDemotion = applyStaleDemotion(tiered);
 
-  // ── Step 10: Budget allocation and two-layer injection ──────────
+  // ── Step 9: Budget allocation and two-layer injection ──────────
   const maxInjectTokens = Math.max(
     1,
     Math.floor(
@@ -581,7 +559,6 @@ export async function buildMemoryRecall(
     {
       query: truncate(query, 120),
       hybridHits: hybridCandidates.length,
-      recencyHits: recencyCandidates.length,
       mergedCount: allCandidates.length,
       tier1Count,
       tier2Count,
@@ -602,7 +579,6 @@ export async function buildMemoryRecall(
     provider: embeddingResult.provider,
     model: embeddingResult.model,
     semanticHits: hybridCandidates.length,
-    recencyHits: recencyCandidates.length,
     mergedCount: allCandidates.length,
     selectedCount,
     injectedTokens: estimateTextTokens(injectedText),
@@ -887,7 +863,6 @@ function emptyResult(
     provider: init.provider,
     model: init.model,
     semanticHits: 0,
-    recencyHits: 0,
     mergedCount: 0,
     selectedCount: 0,
     injectedTokens: 0,

package/src/memory/schema/memory-core.ts

@@ -56,6 +56,8 @@ export const memoryItems = sqliteTable(
     supersedes: text("supersedes"),
     supersededBy: text("superseded_by"),
     overrideConfidence: text("override_confidence").default("inferred"),
+    sourceType: text("source_type").notNull().default("extraction"),
+    sourceMessageRole: text("source_message_role"),
   },
   (table) => [
     index("idx_memory_items_scope_id").on(table.scopeId),

package/src/memory/search/formatting.ts

@@ -80,15 +80,6 @@ export const PREFERENCE_KINDS = new Set(["preference", "constraint"]);
 /** Kinds classified as capabilities for the <available_capabilities> section. */
 export const CAPABILITY_KINDS = new Set(["capability"]);
 
-/** Per-item token budget for tier 1 items. */
-const TIER1_PER_ITEM_TOKENS = 150;
-
-/** Per-item token budget for tier 2 items. */
-const TIER2_PER_ITEM_TOKENS = 100;
-
-/** Approximate chars-per-token for truncation (matches token-estimator). */
-const CHARS_PER_TOKEN = 4;
-
 /**
  * Build a two-layer XML injection block from tiered candidates.
  *
@@ -151,38 +142,21 @@ export function buildTwoLayerInjection(params: {
     : Infinity;
 
   // Render tier 1 items first (identity, relevant context, preferences)
-  const identityLines = renderPlainStatements(
-    identityItems,
-    TIER1_PER_ITEM_TOKENS,
-    remainingTokens,
-  );
+  const identityLines = renderPlainStatements(identityItems, remainingTokens);
   remainingTokens -= estimateTextTokens(identityLines.join("\n"));
 
-  const relevantEpisodes = renderEpisodes(
-    tier1Candidates,
-    TIER1_PER_ITEM_TOKENS,
-    remainingTokens,
-  );
+  const relevantEpisodes = renderEpisodes(tier1Candidates, remainingTokens);
   remainingTokens -= estimateTextTokens(relevantEpisodes.join("\n"));
 
-  const preferenceLines = renderPlainStatements(
-    preferences,
-    TIER1_PER_ITEM_TOKENS,
-    remainingTokens,
-  );
+  const preferenceLines = renderPlainStatements(preferences, remainingTokens);
   remainingTokens -= estimateTextTokens(preferenceLines.join("\n"));
 
-  const capabilityLines = renderPlainStatements(
-    capabilities,
-    TIER1_PER_ITEM_TOKENS,
-    remainingTokens,
-  );
+  const capabilityLines = renderPlainStatements(capabilities, remainingTokens);
   remainingTokens -= estimateTextTokens(capabilityLines.join("\n"));
 
   // Tier 2 uses remaining budget
   const possiblyRelevantEpisodes = renderEpisodesWithStaleness(
     tier2Candidates,
-    TIER2_PER_ITEM_TOKENS,
     remainingTokens,
   );
 
@@ -229,15 +203,13 @@ export function buildTwoLayerInjection(params: {
  */
 function renderPlainStatements(
   items: TieredCandidate[],
-  perItemBudgetTokens: number,
   remainingBudget: number,
 ): string[] {
   const lines: string[] = [];
   let used = 0;
   for (const item of items) {
     if (used >= remainingBudget) break;
-    const maxChars = perItemBudgetTokens * CHARS_PER_TOKEN;
-    const text = escapeXmlTags(truncate(item.text, maxChars));
+    const text = escapeXmlTags(item.text);
     const tokens = estimateTextTokens(text);
     if (used + tokens > remainingBudget) break;
     lines.push(text);
@@ -251,15 +223,13 @@ function renderPlainStatements(
  */
 function renderEpisodes(
   items: TieredCandidate[],
-  perItemBudgetTokens: number,
   remainingBudget: number,
 ): string[] {
   const lines: string[] = [];
   let used = 0;
   for (const item of items) {
     if (used >= remainingBudget) break;
-    const maxChars = perItemBudgetTokens * CHARS_PER_TOKEN;
-    const text = escapeXmlTags(truncate(item.text, maxChars));
+    const text = escapeXmlTags(item.text);
     const sourceAttr = buildSourceAttr(item);
     const line = `<episode${sourceAttr}>\n${text}\n</episode>`;
     const tokens = estimateTextTokens(line);
@@ -275,15 +245,13 @@ function renderEpisodes(
  */
 function renderEpisodesWithStaleness(
   items: TieredCandidate[],
-  perItemBudgetTokens: number,
   remainingBudget: number,
 ): string[] {
   const lines: string[] = [];
   let used = 0;
   for (const item of items) {
     if (used >= remainingBudget) break;
-    const maxChars = perItemBudgetTokens * CHARS_PER_TOKEN;
-    const text = escapeXmlTags(truncate(item.text, maxChars));
+    const text = escapeXmlTags(item.text);
     const sourceAttr = buildSourceAttr(item);
     const stalenessAttr =
       item.staleness && item.staleness !== "fresh"
@@ -347,8 +315,3 @@ function formatShortDate(epochMs: number): string {
   }
   return `${month} ${day} ${date.getFullYear()}`;
 }
-
-function truncate(text: string, max: number): string {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max - 3)}...`;
-}

package/src/memory/search/staleness.ts

@@ -8,6 +8,10 @@ const BASE_LIFETIME_MS: Record<string, number> = {
   project: 14 * 86_400_000, // 2 weeks
   decision: 14 * 86_400_000, // 2 weeks
   event: 3 * 86_400_000, // 3 days
+  // Journals are experiential reflections and forward-looking notes — more
+  // durable than ephemeral events or decisions, but not as permanent as
+  // identity. 90 days mirrors "preference" lifetime.
+  journal: 90 * 86_400_000, // 3 months
   capability: Infinity,
 };
 

package/src/memory/search/tier-classifier.ts

@@ -8,9 +8,17 @@ export interface TieredCandidate extends Candidate {
   sourceLabel?: string;
 }
 
+/**
+ * Map a composite relevance score to an injection tier.
+ *
+ * Thresholds are intentionally set lower than raw-embedding ceilings because
+ * the multiplicative scoring pipeline (semantic × recency × metadata) compresses
+ * the effective score range.  Lowering the gates lets moderately-relevant items
+ * surface rather than being silently dropped.
+ */
 export function classifyTier(score: number): Tier | null {
-  if (score > 0.8) return 1;
-  if (score > 0.6) return 2;
+  if (score > 0.6) return 1;
+  if (score > 0.4) return 2;
   return null;
 }
 

package/src/memory/search/types.ts

@@ -1,5 +1,5 @@
 export type CandidateType = "segment" | "item" | "summary" | "media";
-export type CandidateSource = "semantic" | "recency";
+export type CandidateSource = "semantic";
 
 export type StalenessLevel = "fresh" | "aging" | "stale" | "very_stale";
 
@@ -39,12 +39,10 @@ export type DegradationReason =
   | "qdrant_unavailable"
   | "embedding_generation_failed";
 
-export type FallbackSource = "recency";
-
 export interface DegradationStatus {
   semanticUnavailable: boolean;
   reason: DegradationReason;
-  fallbackSources: FallbackSource[];
+  fallbackSources: string[];
 }
 
 export interface MemoryRecallResult {
@@ -55,7 +53,6 @@ export interface MemoryRecallResult {
   provider?: string;
   model?: string;
   semanticHits: number;
-  recencyHits: number;
   mergedCount: number;
   selectedCount: number;
   injectedTokens: number;

package/src/memory/task-memory-cleanup.ts

@@ -24,14 +24,14 @@ export function isConversationFailed(conversationId: string): boolean {
 }
 
 /**
- * Invalidate `assistant_inferred` memory items sourced *exclusively* from
+ * Invalidate assistant-extracted memory items sourced *exclusively* from
  * messages in the given conversation. Called when a background task or
  * schedule fails — the assistant's optimistic claims (e.g., "I booked an
  * appointment") are not trustworthy if the task didn't complete.
  *
  * The failed state is derived from durable storage (task_runs / cron_runs),
  * so any pending or future extraction jobs for this conversation are blocked
- * from creating new `assistant_inferred` items — even after daemon restarts.
+ * from creating new assistant-extracted items — even after daemon restarts.
  *
  * Items that also have sources from other conversations are left alone
  * only when those conversations come from non-failed task/schedule runs
@@ -55,7 +55,8 @@ export function invalidateAssistantInferredItemsForConversation(
     `UPDATE memory_items
         SET status = 'invalidated',
             invalid_at = ?
-      WHERE verification_state = 'assistant_inferred'
+      WHERE source_type = 'extraction'
+        AND source_message_role = 'assistant'
         AND status = 'active'
         AND id IN (
           SELECT mis.memory_item_id

package/src/notifications/adapters/slack.ts

@@ -13,7 +13,12 @@ import { mintDaemonDeliveryToken } from "../../runtime/auth/token-service.js";
 import { deliverChannelReply } from "../../runtime/gateway-client.js";
 import { getLogger } from "../../util/logger.js";
 import { isConversationSeedSane } from "../conversation-seed-composer.js";
-import { nonEmpty } from "../copy-composer.js";
+import {
+  buildAccessRequestIdentityLine,
+  buildAccessRequestInviteDirective,
+  nonEmpty,
+  sanitizeIdentityField,
+} from "../copy-composer.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
@@ -41,6 +46,149 @@ function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
   return payload.sourceEventName.replace(/[._]/g, " ");
 }
 
+// ---------------------------------------------------------------------------
+// Block Kit helpers for access request 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
+ */
+export function buildAccessRequestBlocks(
+  payload: Record<string, unknown>,
+): unknown[] {
+  const blocks: unknown[] = [];
+
+  // Header
+  blocks.push({
+    type: "header",
+    text: { type: "plain_text", text: "New access request", emoji: true },
+  });
+
+  // Requester identity section
+  const identityLine = buildAccessRequestIdentityLine(payload);
+  blocks.push({
+    type: "section",
+    text: { type: "mrkdwn", text: identityLine },
+  });
+
+  // Build fields for structured requester details
+  const fields: Array<{ type: "mrkdwn"; text: string }> = [];
+
+  const senderIdentifier = nonEmpty(
+    typeof payload.senderIdentifier === "string"
+      ? sanitizeIdentityField(payload.senderIdentifier)
+      : undefined,
+  );
+  if (senderIdentifier) {
+    fields.push({ type: "mrkdwn", text: `*Name:*\n${senderIdentifier}` });
+  }
+
+  const actorUsername = nonEmpty(
+    typeof payload.actorUsername === "string"
+      ? sanitizeIdentityField(payload.actorUsername)
+      : undefined,
+  );
+  if (actorUsername) {
+    fields.push({ type: "mrkdwn", text: `*Username:*\n@${actorUsername}` });
+  }
+
+  const sourceChannel = nonEmpty(
+    typeof payload.sourceChannel === "string"
+      ? payload.sourceChannel
+      : undefined,
+  );
+  if (sourceChannel) {
+    fields.push({ type: "mrkdwn", text: `*Channel:*\n${sourceChannel}` });
+  }
+
+  const actorExternalId = nonEmpty(
+    typeof payload.actorExternalId === "string"
+      ? sanitizeIdentityField(payload.actorExternalId)
+      : undefined,
+  );
+  if (actorExternalId && actorExternalId !== senderIdentifier) {
+    fields.push({ type: "mrkdwn", text: `*ID:*\n${actorExternalId}` });
+  }
+
+  if (fields.length > 0) {
+    blocks.push({
+      type: "section",
+      fields,
+    });
+  }
+
+  // Previously revoked warning
+  const previousMemberStatus =
+    typeof payload.previousMemberStatus === "string"
+      ? payload.previousMemberStatus
+      : undefined;
+  if (previousMemberStatus === "revoked") {
+    blocks.push({
+      type: "context",
+      elements: [
+        {
+          type: "mrkdwn",
+          text: ":warning: This user was previously revoked.",
+        },
+      ],
+    });
+  }
+
+  // Divider before instructions
+  blocks.push({ type: "divider" });
+
+  // Approval code instructions
+  const requestCode = nonEmpty(
+    typeof payload.requestCode === "string" ? payload.requestCode : undefined,
+  );
+  if (requestCode) {
+    const code = requestCode.toUpperCase();
+    blocks.push({
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: `Reply *\`${code} approve\`* to grant access or *\`${code} reject\`* to deny.`,
+      },
+    });
+  }
+
+  // Invite directive
+  const inviteDirective = buildAccessRequestInviteDirective();
+  blocks.push({
+    type: "context",
+    elements: [{ type: "mrkdwn", text: inviteDirective }],
+  });
+
+  // Guardian verification note
+  const guardianResolutionSource =
+    typeof payload.guardianResolutionSource === "string"
+      ? payload.guardianResolutionSource
+      : undefined;
+  if (
+    (guardianResolutionSource === "vellum-anchor" ||
+      guardianResolutionSource === "none") &&
+    sourceChannel
+  ) {
+    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 blocks;
+}
+
 export class SlackAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = "slack";
 
@@ -65,12 +213,26 @@ 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 {
-      await deliverChannelReply(
-        deliverUrl,
-        { chatId, text: messageText, useBlocks: true },
-        mintDaemonDeliveryToken(),
-      );
+      if (isAccessRequest) {
+        const blocks = buildAccessRequestBlocks(payload.contextPayload!);
+        await deliverChannelReply(
+          deliverUrl,
+          { chatId, text: messageText, blocks },
+          mintDaemonDeliveryToken(),
+        );
+      } else {
+        await deliverChannelReply(
+          deliverUrl,
+          { chatId, text: messageText, useBlocks: true },
+          mintDaemonDeliveryToken(),
+        );
+      }
 
       log.info(
         { sourceEventName: payload.sourceEventName, chatId },

package/src/notifications/broadcaster.ts

@@ -271,6 +271,7 @@ export class NotificationBroadcaster {
         sourceEventName: signal.sourceEventName,
         copy,
         deepLinkTarget,
+        contextPayload: signal.contextPayload,
       };
 
       // Compute conversation decision audit fields for the delivery record

package/src/notifications/copy-composer.ts

@@ -99,7 +99,14 @@ export function buildAccessRequestIdentityLine(
   const sanitizedExternalId = actorExternalId
     ? sanitizeIdentityField(actorExternalId)
     : undefined;
-  const parts = [requester];
+  // When the requester is a raw Slack user ID (e.g. the fallback path in
+  // access-request-helper sets senderIdentifier to the raw actorExternalId),
+  // format it as a Slack mention so it renders as a clickable display name.
+  const formattedRequester =
+    sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(requester)
+      ? `<@${requester}>`
+      : requester;
+  const parts = [formattedRequester];
   if (sanitizedUsername && sanitizedUsername !== requester) {
     parts.push(`@${sanitizedUsername}`);
   }
@@ -108,7 +115,13 @@ export function buildAccessRequestIdentityLine(
     sanitizedExternalId !== requester &&
     sanitizedExternalId !== sanitizedUsername
   ) {
-    parts.push(`[${sanitizedExternalId}]`);
+    // For Slack, use the <@U...> mention format so Slack auto-renders
+    // the user ID as a clickable display name.
+    const formattedId =
+      sourceChannel === "slack" && /^U[A-Z0-9]+$/i.test(sanitizedExternalId)
+        ? `<@${sanitizedExternalId}>`
+        : `[${sanitizedExternalId}]`;
+    parts.push(formattedId);
   }
   if (sourceChannel) {
     parts.push(`via ${sourceChannel}`);
@@ -117,6 +130,46 @@ export function buildAccessRequestIdentityLine(
   return `${parts.join(" ")} is requesting access to the assistant.`;
 }
 
+export const MESSAGE_PREVIEW_MAX_LENGTH = 200;
+
+/**
+ * Sanitize an untrusted message preview for inclusion in notification copy.
+ *
+ * Like {@link sanitizeIdentityField} but uses the higher
+ * MESSAGE_PREVIEW_MAX_LENGTH limit (200 chars) instead of the identity
+ * field limit (120 chars).
+ */
+export function sanitizeMessagePreview(value: string): string {
+  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
+  const clamped =
+    stripped.length > MESSAGE_PREVIEW_MAX_LENGTH
+      ? stripped.slice(0, MESSAGE_PREVIEW_MAX_LENGTH) + "…"
+      : stripped;
+  return clamped;
+}
+
+/**
+ * Build a quoted preview of the requester's original message for inclusion
+ * in guardian-facing access-request copy. Sanitizes and truncates to keep
+ * the notification concise.
+ *
+ * Returns `undefined` when no usable preview is available.
+ */
+export function buildAccessRequestMessagePreview(
+  payload: Record<string, unknown>,
+): string | undefined {
+  const raw =
+    typeof payload.messagePreview === "string"
+      ? payload.messagePreview
+      : undefined;
+  if (!raw) return undefined;
+
+  const sanitized = sanitizeMessagePreview(raw);
+  if (sanitized.length === 0) return undefined;
+
+  return `> Their message: "${sanitized}"`;
+}
+
 export function buildAccessRequestInviteDirective(): string {
   return 'Reply "open invite flow" to start Trusted Contacts invite flow.';
 }
@@ -227,6 +280,10 @@ export function buildAccessRequestContractText(
 
   const lines: string[] = [];
   lines.push(buildAccessRequestIdentityLine(payload));
+  const preview = buildAccessRequestMessagePreview(payload);
+  if (preview) {
+    lines.push(preview);
+  }
   if (previousMemberStatus === "revoked") {
     lines.push("Note: this user was previously revoked.");
   }