@vellumai/assistant 0.5.16 → 0.6.1

package/src/__tests__/workspace-migration-028-recover-conversations-from-disk-view.test.ts

@@ -0,0 +1,387 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks — must come before any imports that depend on them
+// ---------------------------------------------------------------------------
+
+const testDir = process.env.VELLUM_WORKSPACE_DIR!;
+const workspaceDir = testDir;
+const conversationsDir = join(workspaceDir, "conversations");
+mkdirSync(conversationsDir, { recursive: true });
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+  }),
+}));
+
+// ---------------------------------------------------------------------------
+// Imports — after mocks
+// ---------------------------------------------------------------------------
+
+import { getDb, initializeDb } from "../memory/db.js";
+import { conversations, messages } from "../memory/schema.js";
+import { recoverConversationsFromDiskViewMigration } from "../workspace/migrations/028-recover-conversations-from-disk-view.js";
+
+initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resetTables() {
+  const db = getDb();
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+function resetConversationsDir() {
+  rmSync(conversationsDir, { recursive: true, force: true });
+  mkdirSync(conversationsDir, { recursive: true });
+}
+
+function createDiskViewDir(
+  id: string,
+  meta: Record<string, unknown>,
+  messagesJsonl?: string,
+): string {
+  const createdAt =
+    typeof meta.createdAt === "string" ? meta.createdAt : new Date().toISOString();
+  const timestamp = createdAt.replace(/:/g, "-");
+  const dirName = `${timestamp}_${id}`;
+  const dirPath = join(conversationsDir, dirName);
+  mkdirSync(dirPath, { recursive: true });
+  writeFileSync(join(dirPath, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
+  if (messagesJsonl !== undefined) {
+    writeFileSync(join(dirPath, "messages.jsonl"), messagesJsonl);
+  }
+  return dirPath;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("028-recover-conversations-from-disk-view migration", () => {
+  beforeEach(() => {
+    resetTables();
+    resetConversationsDir();
+  });
+
+  test("recovers conversation with messages", () => {
+    const id = "conv-028-basic";
+    const createdAt = "2026-03-18T14:23:00.000Z";
+    const updatedAt = "2026-03-18T14:25:00.000Z";
+
+    const userLine = JSON.stringify({
+      role: "user",
+      ts: "2026-03-18T14:23:30.000Z",
+      content: "Hello, world",
+    });
+    const assistantLine = JSON.stringify({
+      role: "assistant",
+      ts: "2026-03-18T14:24:00.000Z",
+      content: "Hi there!",
+    });
+
+    createDiskViewDir(
+      id,
+      { id, title: "Basic Recovery", type: "standard", channel: "desktop", createdAt, updatedAt },
+      userLine + "\n" + assistantLine + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(1);
+    expect(convRows[0].id).toBe(id);
+    expect(convRows[0].title).toBe("Basic Recovery");
+    expect(convRows[0].conversationType).toBe("standard");
+    expect(convRows[0].createdAt).toBe(Date.parse(createdAt));
+    expect(convRows[0].updatedAt).toBe(Date.parse(updatedAt));
+
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(2);
+
+    const userMsg = msgRows.find((m) => m.role === "user")!;
+    expect(userMsg).toBeDefined();
+    const userContent = JSON.parse(userMsg.content);
+    expect(userContent).toEqual([{ type: "text", text: "Hello, world" }]);
+    expect(userMsg.createdAt).toBe(Date.parse("2026-03-18T14:23:30.000Z"));
+
+    const assistantMsg = msgRows.find((m) => m.role === "assistant")!;
+    expect(assistantMsg).toBeDefined();
+    const assistantContent = JSON.parse(assistantMsg.content);
+    expect(assistantContent).toEqual([{ type: "text", text: "Hi there!" }]);
+    expect(assistantMsg.createdAt).toBe(Date.parse("2026-03-18T14:24:00.000Z"));
+  });
+
+  test("handles toolCalls and toolResults", () => {
+    const id = "conv-028-tools";
+    const createdAt = "2026-03-18T15:00:00.000Z";
+
+    const toolCallLine = JSON.stringify({
+      role: "assistant",
+      ts: "2026-03-18T15:00:10.000Z",
+      toolCalls: [{ name: "bash", input: { command: "ls" } }],
+    });
+    const toolResultLine = JSON.stringify({
+      role: "user",
+      ts: "2026-03-18T15:00:20.000Z",
+      toolResults: [{ content: "file.txt" }],
+    });
+
+    createDiskViewDir(
+      id,
+      { id, title: "Tool Test", type: "standard", createdAt, updatedAt: createdAt },
+      toolCallLine + "\n" + toolResultLine + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(2);
+
+    const assistantMsg = msgRows.find((m) => m.role === "assistant")!;
+    const assistantContent = JSON.parse(assistantMsg.content);
+    expect(assistantContent).toHaveLength(1);
+    expect(assistantContent[0].type).toBe("tool_use");
+    expect(assistantContent[0].name).toBe("bash");
+    expect(assistantContent[0].input).toEqual({ command: "ls" });
+    // tool_use blocks get a random UUID id — just check it's a string
+    expect(typeof assistantContent[0].id).toBe("string");
+
+    const userMsg = msgRows.find((m) => m.role === "user")!;
+    const userContent = JSON.parse(userMsg.content);
+    expect(userContent).toHaveLength(1);
+    expect(userContent[0].type).toBe("tool_result");
+    expect(userContent[0].content).toBe("file.txt");
+    expect(userContent[0].tool_use_id).toBe("");
+  });
+
+  test("handles mixed content + toolCalls on the same message", () => {
+    const id = "conv-028-mixed";
+    const createdAt = "2026-03-18T15:30:00.000Z";
+
+    const mixedLine = JSON.stringify({
+      role: "assistant",
+      ts: "2026-03-18T15:30:10.000Z",
+      content: "Let me check that",
+      toolCalls: [{ name: "bash", input: { command: "ls" } }],
+    });
+
+    createDiskViewDir(
+      id,
+      { id, title: "Mixed Test", type: "standard", createdAt, updatedAt: createdAt },
+      mixedLine + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(1);
+
+    const assistantMsg = msgRows[0];
+    expect(assistantMsg.role).toBe("assistant");
+
+    const contentBlocks = JSON.parse(assistantMsg.content);
+    expect(contentBlocks).toHaveLength(2);
+
+    expect(contentBlocks[0].type).toBe("text");
+    expect(contentBlocks[0].text).toBe("Let me check that");
+
+    expect(contentBlocks[1].type).toBe("tool_use");
+    expect(contentBlocks[1].name).toBe("bash");
+    expect(contentBlocks[1].input).toEqual({ command: "ls" });
+    expect(typeof contentBlocks[1].id).toBe("string");
+  });
+
+  test("skips existing conversations", () => {
+    const id = "conv-028-existing";
+    const createdAt = "2026-03-18T16:00:00.000Z";
+    const createdAtMs = Date.parse(createdAt);
+
+    // Pre-insert the conversation in the DB
+    const db = getDb();
+    db.insert(conversations)
+      .values({
+        id,
+        title: "Already Here",
+        createdAt: createdAtMs,
+        updatedAt: createdAtMs,
+        conversationType: "standard",
+        source: "user",
+        memoryScopeId: "default",
+      })
+      .run();
+
+    // Create matching disk-view dir with a message
+    createDiskViewDir(
+      id,
+      { id, title: "Already Here", type: "standard", createdAt, updatedAt: createdAt },
+      JSON.stringify({ role: "user", ts: createdAt, content: "Should not be imported" }) + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    // Verify no duplication: still 1 conversation, 0 messages (the disk-view message was not imported)
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(1);
+    expect(convRows[0].title).toBe("Already Here");
+
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(0);
+  });
+
+  test("idempotent — running twice produces same result", () => {
+    const id = "conv-028-idem";
+    const createdAt = "2026-03-18T17:00:00.000Z";
+
+    createDiskViewDir(
+      id,
+      { id, title: "Idempotency Test", type: "standard", createdAt, updatedAt: createdAt },
+      JSON.stringify({ role: "user", ts: createdAt, content: "First message" }) + "\n" +
+        JSON.stringify({ role: "assistant", ts: "2026-03-18T17:01:00.000Z", content: "Reply" }) + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convCountAfterFirst = db.select().from(conversations).all().length;
+    const msgCountAfterFirst = db.select().from(messages).all().length;
+    expect(convCountAfterFirst).toBe(1);
+    expect(msgCountAfterFirst).toBe(2);
+
+    // Run again
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const convCountAfterSecond = db.select().from(conversations).all().length;
+    const msgCountAfterSecond = db.select().from(messages).all().length;
+    expect(convCountAfterSecond).toBe(convCountAfterFirst);
+    expect(msgCountAfterSecond).toBe(msgCountAfterFirst);
+  });
+
+  test("handles missing messages.jsonl", () => {
+    const id = "conv-028-no-messages";
+    const createdAt = "2026-03-18T18:00:00.000Z";
+
+    // Create dir with only meta.json — no messages.jsonl
+    createDiskViewDir(
+      id,
+      { id, title: "No Messages", type: "standard", createdAt, updatedAt: createdAt },
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(1);
+    expect(convRows[0].id).toBe(id);
+    expect(convRows[0].title).toBe("No Messages");
+
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(0);
+  });
+
+  test("handles malformed JSONL lines", () => {
+    const id = "conv-028-malformed-jsonl";
+    const createdAt = "2026-03-18T19:00:00.000Z";
+
+    const validLine = JSON.stringify({ role: "user", ts: createdAt, content: "Valid" });
+    const invalidLine = "{ this is not valid json }}}";
+
+    createDiskViewDir(
+      id,
+      { id, title: "Malformed JSONL", type: "standard", createdAt, updatedAt: createdAt },
+      validLine + "\n" + invalidLine + "\n",
+    );
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(1);
+
+    // Only the valid line should produce a message row
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(1);
+    expect(msgRows[0].role).toBe("user");
+    const content = JSON.parse(msgRows[0].content);
+    expect(content).toEqual([{ type: "text", text: "Valid" }]);
+  });
+
+  test("handles malformed meta.json", () => {
+    const id = "conv-028-malformed-meta";
+    const createdAt = "2026-03-18T20:00:00.000Z";
+    const timestamp = createdAt.replace(/:/g, "-");
+    const dirName = `${timestamp}_${id}`;
+    const dirPath = join(conversationsDir, dirName);
+    mkdirSync(dirPath, { recursive: true });
+
+    // Write broken JSON directly
+    writeFileSync(join(dirPath, "meta.json"), "{ broken json");
+
+    // Migration should complete without error
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(0);
+  });
+
+  test("no-op when conversations dir missing", () => {
+    // Remove the conversations dir entirely
+    rmSync(conversationsDir, { recursive: true, force: true });
+    expect(existsSync(conversationsDir)).toBe(false);
+
+    // Migration should complete without error
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    // No conversations should exist since we can't access the DB rows through a missing dir
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(0);
+  });
+
+  test("processes multiple directories", () => {
+    const ids = ["conv-028-multi-a", "conv-028-multi-b", "conv-028-multi-c"];
+    const baseTime = Date.parse("2026-03-18T21:00:00.000Z");
+
+    for (let i = 0; i < ids.length; i++) {
+      const ts = new Date(baseTime + i * 60_000).toISOString();
+      createDiskViewDir(
+        ids[i],
+        { id: ids[i], title: `Multi ${i + 1}`, type: "standard", createdAt: ts, updatedAt: ts },
+        JSON.stringify({ role: "user", ts, content: `Message ${i + 1}` }) + "\n",
+      );
+    }
+
+    recoverConversationsFromDiskViewMigration.run(workspaceDir);
+
+    const db = getDb();
+    const convRows = db.select().from(conversations).all();
+    expect(convRows).toHaveLength(3);
+
+    const recoveredIds = convRows.map((c) => c.id).sort();
+    expect(recoveredIds).toEqual([...ids].sort());
+
+    const msgRows = db.select().from(messages).all();
+    expect(msgRows).toHaveLength(3);
+  });
+});

package/src/__tests__/workspace-policy.test.ts

@@ -257,7 +257,7 @@ describe("isWorkspaceScopedInvocation", () => {
   describe("always-scoped tools", () => {
     const safeTools = [
       "skill_load",
-      "memory_recall",
+      "recall",
       "ui_update",
       "ui_dismiss",
     ];

package/src/agent/attachments.ts

@@ -1,4 +1,5 @@
 import type { ContentBlock, Message } from "../providers/types.js";
+import { optimizeImageForTransport } from "./image-optimize.js";
 
 export interface MessageAttachmentInput {
   id?: string;
@@ -14,12 +15,16 @@ export function attachmentsToContentBlocks(
 ): ContentBlock[] {
   return attachments.map((attachment) => {
     if (attachment.mimeType.toLowerCase().startsWith("image/")) {
+      const { data, mediaType } = optimizeImageForTransport(
+        attachment.data,
+        attachment.mimeType,
+      );
       return {
         type: "image",
         source: {
           type: "base64",
-          media_type: attachment.mimeType,
-          data: attachment.data,
+          media_type: mediaType,
+          data,
         },
       } as ContentBlock;
     }

package/src/agent/image-optimize.ts

@@ -0,0 +1,165 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parseImageDimensions } from "../context/image-dimensions.js";
+
+// Anthropic's documented max dimension — images larger than this are scaled
+// down server-side anyway, so pre-scaling is zero quality loss.
+const MAX_DIMENSION = 1568;
+
+// Threshold below which we skip optimization — small images don't need it.
+const OPTIMIZE_THRESHOLD_BYTES = 300 * 1024; // 300 KB
+
+const JPEG_QUALITY = 80;
+
+// Content-addressed disk cache to avoid re-running sips on the same image.
+const CACHE_MAX_ENTRIES = 500;
+
+function getCacheDir(): string {
+  return join(tmpdir(), "vellum-optimized-images");
+}
+
+function readFromCache(
+  key: string,
+): { data: string; mediaType: string } | null {
+  try {
+    const cachePath = join(getCacheDir(), `${key}.jpg`);
+    if (!existsSync(cachePath)) return null;
+    const buf = readFileSync(cachePath) as Buffer;
+    return { data: buf.toString("base64"), mediaType: "image/jpeg" };
+  } catch {
+    return null;
+  }
+}
+
+function writeToCache(key: string, optimizedBytes: Buffer): void {
+  try {
+    const dir = getCacheDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${key}.jpg`), optimizedBytes);
+    evictIfNeeded(dir);
+  } catch {
+    // Cache write failure is non-fatal.
+  }
+}
+
+function evictIfNeeded(dir: string): void {
+  try {
+    const entries = readdirSync(dir)
+      .filter((f) => f.endsWith(".jpg"))
+      .map((f) => {
+        const full = join(dir, f);
+        return { path: full, mtimeMs: statSync(full).mtimeMs };
+      })
+      .sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const excess = entries.length - CACHE_MAX_ENTRIES;
+    for (let i = 0; i < excess; i++) {
+      try {
+        unlinkSync(entries[i]!.path);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+function runSips(inputBytes: Buffer): Buffer | null {
+  const srcPath = join(tmpdir(), `vellum-img-opt-${Date.now()}-src`);
+  const outPath = join(tmpdir(), `vellum-img-opt-${Date.now()}-out.jpg`);
+  try {
+    writeFileSync(srcPath, inputBytes);
+    execFileSync(
+      "sips",
+      [
+        "--resampleHeightWidthMax",
+        String(MAX_DIMENSION),
+        "-s",
+        "format",
+        "jpeg",
+        "-s",
+        "formatOptions",
+        String(JPEG_QUALITY),
+        srcPath,
+        "--out",
+        outPath,
+      ],
+      { stdio: "pipe", timeout: 15_000 },
+    );
+    return readFileSync(outPath) as Buffer;
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(srcPath);
+    } catch {
+      /* ignore */
+    }
+    try {
+      unlinkSync(outPath);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Downscale a base64 image to fit within Anthropic's recommended dimensions
+ * (1568px max side). Returns the original data unchanged if the image is
+ * already small enough or if optimization fails.
+ *
+ * Anthropic applies the same scaling server-side, so this is zero quality
+ * loss — we just do it pre-flight to keep request payloads small and avoid
+ * 413 "request too large" errors when many images accumulate in context.
+ *
+ * Results are cached on disk by content hash so repeated sends of the same
+ * image (or daemon restarts) skip the sips call entirely.
+ */
+export function optimizeImageForTransport(
+  base64Data: string,
+  mediaType: string,
+): { data: string; mediaType: string } {
+  const rawBytes = Buffer.from(base64Data, "base64");
+
+  // Small images don't need optimization.
+  if (rawBytes.length <= OPTIMIZE_THRESHOLD_BYTES) {
+    return { data: base64Data, mediaType };
+  }
+
+  // If dimensions are already within limits, skip.
+  const dims = parseImageDimensions(base64Data, mediaType);
+  if (
+    dims &&
+    dims.width <= MAX_DIMENSION &&
+    dims.height <= MAX_DIMENSION
+  ) {
+    return { data: base64Data, mediaType };
+  }
+
+  // Content-addressed cache lookup.
+  const hash = createHash("sha256").update(rawBytes).digest("hex");
+  const cacheKey = hash.slice(0, 16);
+  const cached = readFromCache(cacheKey);
+  if (cached) return cached;
+
+  // Run sips (macOS). On other platforms this gracefully returns null.
+  const optimized = runSips(rawBytes);
+  if (!optimized) {
+    return { data: base64Data, mediaType };
+  }
+
+  writeToCache(cacheKey, optimized);
+  return { data: optimized.toString("base64"), mediaType: "image/jpeg" };
+}

package/src/agent/loop.ts

@@ -31,6 +31,8 @@ export interface AgentLoopConfig {
     | { type: "tool"; name: string };
   /** Minimum interval (ms) between consecutive LLM calls to prevent spin when tools return instantly */
   minTurnIntervalMs?: number;
+  /** Override the default prompt cache TTL sent to the provider (e.g. "5m" for short-lived subagents). */
+  cacheTtl?: "5m" | "1h";
 }
 
 export interface CheckpointInfo {
@@ -101,10 +103,7 @@ const DEFAULT_CONFIG: AgentLoopConfig = {
   minTurnIntervalMs: 150,
 };
 
-const PROGRESS_CHECK_INTERVAL = 5;
 const MAX_CONSECUTIVE_ERROR_NUDGES = 3;
-const PROGRESS_CHECK_REMINDER =
-  "You have been using tools for several turns. Check whether you are making meaningful progress toward the user's goal. If you are stuck in a loop or not making progress, summarize what you have tried and ask the user for guidance instead of continuing.";
 
 export interface ResolvedSystemPrompt {
   systemPrompt: string;
@@ -255,6 +254,10 @@ export class AgentLoop {
           providerConfig.tool_choice = this.config.toolChoice;
         }
 
+        if (this.config.cacheTtl) {
+          providerConfig.cacheTtl = this.config.cacheTtl;
+        }
+
         const preLlmResult = await getHookManager().trigger("pre-llm-call", {
           systemPrompt: turnSystemPrompt,
           messages: history,
@@ -573,21 +576,11 @@ export class AgentLoop {
           break;
         }
 
-        // Track tool-use turns and inject progress reminder every N turns
         toolUseTurns++;
-        const isProgressCheckTurn =
-          toolUseTurns % PROGRESS_CHECK_INTERVAL === 0;
-        if (isProgressCheckTurn) {
-          resultBlocks.push({
-            type: "text",
-            text: `<system_notice>${PROGRESS_CHECK_REMINDER}</system_notice>`,
-          });
-        }
 
         // When any tool returned an error, nudge the LLM to retry with
         // corrected parameters instead of ending its turn. Skip the nudge
-        // when the progress check fires (to avoid contradictory instructions)
-        // and after MAX_CONSECUTIVE_ERROR_NUDGES consecutive error turns
+        // after MAX_CONSECUTIVE_ERROR_NUDGES consecutive error turns
         // (the error is likely unrecoverable at that point).
         const hasToolError = toolResults.some(({ result }) => result.isError);
         if (hasToolError) {
@@ -597,7 +590,6 @@ export class AgentLoop {
         }
         if (
           hasToolError &&
-          !isProgressCheckTurn &&
           consecutiveErrorTurns <= MAX_CONSECUTIVE_ERROR_NUDGES
         ) {
           resultBlocks.push({

package/src/approvals/guardian-request-resolvers.ts

@@ -13,6 +13,7 @@
 
 import { answerCall } from "../calls/call-domain.js";
 import { getGatewayInternalBaseUrl } from "../config/env.js";
+import { findContactChannel } from "../contacts/contact-store.js";
 import { upsertContactChannel } from "../contacts/contacts-write.js";
 import {
   type CanonicalGuardianRequest,
@@ -396,6 +397,25 @@ const accessRequestResolver: GuardianRequestResolver = {
     const desktopDeliverUrl = resolveDeliverCallbackUrlForChannel(channel);
     const desktopBearerToken = mintDaemonDeliveryToken();
 
+    // Resolve display names from the contacts database for enriched payloads
+    const requesterContactResult = requesterExternalUserId
+      ? findContactChannel({
+          channelType: channel,
+          externalUserId: requesterExternalUserId,
+        })
+      : null;
+    const requesterDisplayName =
+      requesterContactResult?.contact.displayName ?? null;
+
+    const decidedByContactResult = decidedByExternalUserId
+      ? findContactChannel({
+          channelType: channel,
+          externalUserId: decidedByExternalUserId,
+        })
+      : null;
+    const decidedByDisplayName =
+      decidedByContactResult?.contact.displayName ?? null;
+
     if (decision.action === "reject") {
       log.info(
         { event: "resolver_access_request_denied", requestId: request.id },
@@ -435,6 +455,8 @@ const accessRequestResolver: GuardianRequestResolver = {
           requesterExternalUserId,
           requesterChatId,
           decidedByExternalUserId,
+          requesterDisplayName,
+          decidedByDisplayName,
           decision: "denied" as const,
         };
 
@@ -726,6 +748,8 @@ const accessRequestResolver: GuardianRequestResolver = {
             sourceChannel: channel,
             requesterExternalUserId,
             requesterChatId,
+            requesterDisplayName,
+            decidedByDisplayName,
             verificationSessionId: session.sessionId,
           },
           dedupeKey: `trusted-contact:verification-sent:${session.sessionId}`,