@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/runtime/routes/__tests__/contact-routes.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Unit tests for the contacts read API.
+ *
+ * `handleListContacts`, `handleGetContact`, and the `search_contacts`
+ * no-filter case relay to the gateway rich read (`contacts_list_rich` /
+ * `contacts_get_rich`), which is the source of truth for the ACL fields
+ * (`role`/`status`/`policy`/`verifiedAt`/`interactionCount`/`lastInteraction`).
+ * These tests assert the serialized response shape is gateway-sourced and
+ * unchanged for the web client, that no read path falls back to the assistant
+ * DB, and that a relay failure fails closed (surfaces an error) instead of
+ * reading local ACL.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
+
+let ipcCalls: { method: string; params?: Record<string, unknown> }[] = [];
+let ipcResult: unknown = {};
+let ipcError: Error | undefined;
+
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcError) throw ipcError;
+    return ipcResult;
+  },
+);
+
+const actualGatewayClient = await import("../../../ipc/gateway-client.js");
+
+mock.module("../../../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+// Guard: fail loudly if any read path falls back to the assistant DB for ACL
+// fields. The relay read paths must source role/status/stats from the gateway.
+const actualContactStore = await import("../../../contacts/contact-store.js");
+
+const contactStoreReadGuard = mock(() => {
+  throw new Error(
+    "assistant contact-store read must not happen on the gateway relay path",
+  );
+});
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...actualContactStore,
+  getContact: contactStoreReadGuard,
+  listContacts: contactStoreReadGuard,
+  getAssistantContactMetadata: contactStoreReadGuard,
+}));
+
+const { handleListContacts, handleGetContact, ROUTES } = await import(
+  "../contact-routes.js"
+);
+
+const gatewayChannel = {
+  id: "ch_1",
+  contactId: "ct_1",
+  type: "sms",
+  address: "+15550100",
+  isPrimary: true,
+  externalUserId: null,
+  status: "active",
+  policy: "allow",
+  verifiedAt: 1700,
+  verifiedVia: "invite",
+  lastSeenAt: 1800,
+  interactionCount: 7,
+  lastInteraction: 1900,
+  revokedReason: null,
+  blockedReason: null,
+};
+
+const gatewayContact = {
+  id: "ct_1",
+  displayName: "Alice",
+  role: "member",
+  notes: "a note",
+  contactType: "human",
+  lastInteraction: 1900,
+  interactionCount: 7,
+  createdAt: 1000,
+  updatedAt: 1500,
+  channels: [gatewayChannel],
+};
+
+describe("contacts read API relays from the gateway", () => {
+  beforeEach(() => {
+    ipcCalls = [];
+    ipcResult = {};
+    ipcError = undefined;
+    ipcCallPersistentMock.mockClear();
+    contactStoreReadGuard.mockClear();
+  });
+
+  test("list relays to contacts_list_rich and serializes the gateway ACL fields", async () => {
+    ipcResult = { ok: true, contacts: [gatewayContact] };
+
+    const result = await handleListContacts({ limit: "50" });
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_list_rich", params: { limit: 50 } },
+    ]);
+    expect(result.ok).toBe(true);
+    expect(result.contacts).toHaveLength(1);
+
+    const [contact] = result.contacts;
+    // ACL fields are gateway-sourced and reach the web client unchanged.
+    expect(contact.role).toBe("member");
+    expect(contact.interactionCount).toBe(7);
+    expect(contact.lastInteraction).toBe(1900);
+    const channel = contact.channels[0] as Record<string, unknown>;
+    expect(channel.status).toBe("active");
+    expect(channel.policy).toBe("allow");
+    expect(channel.verifiedAt).toBe(1700);
+    expect(channel.interactionCount).toBe(7);
+    expect(channel.lastInteraction).toBe(1900);
+    // Channel compat echoes address into externalUserId for older clients.
+    expect(channel.externalUserId).toBe("+15550100");
+
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("list forwards the role filter to the gateway", async () => {
+    ipcResult = { ok: true, contacts: [] };
+
+    await handleListContacts({ limit: "10", role: "guardian" });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: "contacts_list_rich",
+        params: { limit: 10, role: "guardian" },
+      },
+    ]);
+  });
+
+  test("list fails closed when the gateway relay is unavailable", async () => {
+    ipcError = new IpcCallError("gateway down", {
+      statusCode: 503,
+      errorCode: "UNAVAILABLE",
+    });
+
+    await expect(handleListContacts({ limit: "50" })).rejects.toMatchObject({
+      message: "gateway down",
+      statusCode: 503,
+    });
+    // No assistant-DB fallback read.
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get relays to contacts_get_rich and serializes the gateway ACL fields", async () => {
+    ipcResult = { ok: true, contact: gatewayContact };
+
+    const result = await handleGetContact("ct_1");
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_get_rich", params: { contactId: "ct_1" } },
+    ]);
+    expect(result.ok).toBe(true);
+    expect(result.contact.role).toBe("member");
+    expect(result.contact.interactionCount).toBe(7);
+    const channel = result.contact.channels[0] as Record<string, unknown>;
+    expect(channel.status).toBe("active");
+    expect(channel.externalUserId).toBe("+15550100");
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get surfaces a clean gateway not-found as a 404", async () => {
+    ipcResult = { ok: true };
+
+    await expect(handleGetContact("missing")).rejects.toMatchObject({
+      statusCode: 404,
+    });
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("get fails closed on a relay failure (no assistant-DB fallback)", async () => {
+    ipcError = new IpcCallError("gateway down", {
+      statusCode: 503,
+      errorCode: "UNAVAILABLE",
+    });
+
+    await expect(handleGetContact("ct_1")).rejects.toMatchObject({
+      message: "gateway down",
+      statusCode: 503,
+    });
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+
+  test("search no-filter relays to the gateway list read", async () => {
+    ipcResult = { ok: true, contacts: [gatewayContact] };
+
+    const route = ROUTES.find((r) => r.operationId === "search_contacts");
+    expect(route).toBeDefined();
+
+    const contacts = (await route!.handler({ body: {} })) as Array<{
+      role: string;
+      interactionCount: number;
+      channels: { status: string }[];
+    }>;
+
+    expect(ipcCalls).toEqual([
+      { method: "contacts_list_rich", params: { limit: 50 } },
+    ]);
+    expect(contacts[0].role).toBe("member");
+    expect(contacts[0].interactionCount).toBe(7);
+    expect(contacts[0].channels[0].status).toBe("active");
+    expect(contactStoreReadGuard).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/routes/__tests__/global-search-routes.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for the global-search contacts ordering source.
+ *
+ * Recency ordering for contacts surfaces `contacts.updatedAt`, never the
+ * channel-derived `lastInteraction` column. Daemon-native contact search
+ * carries no gateway-relayed ContactRead, so `updatedAt` is the deterministic
+ * ordering key.
+ */
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { ContactWithChannels } from "../../../contacts/types.js";
+
+let searchContactsResult: ContactWithChannels[] = [];
+
+const searchContactsMock = mock(() => searchContactsResult);
+
+const actualContactStore = await import("../../../contacts/contact-store.js");
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...actualContactStore,
+  searchContacts: searchContactsMock,
+}));
+
+const { ROUTES } = await import("../global-search-routes.js");
+
+const handler = ROUTES.find((r) => r.operationId === "search_global")!.handler;
+
+function makeContact(
+  overrides: Partial<ContactWithChannels>,
+): ContactWithChannels {
+  return {
+    id: "ct_1",
+    displayName: "Alice",
+    notes: null,
+    lastInteraction: null,
+    interactionCount: 0,
+    createdAt: 1,
+    updatedAt: 1,
+    role: "contact",
+    contactType: "human",
+    principalId: null,
+    userFile: null,
+    channels: [],
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  searchContactsResult = [];
+  searchContactsMock.mockClear();
+});
+
+describe("global-search contacts recency source", () => {
+  test("surfaces contacts.updatedAt as lastInteraction, not the channel column", async () => {
+    searchContactsResult = [
+      makeContact({
+        id: "ct_1",
+        displayName: "Alice",
+        updatedAt: 5000,
+        lastInteraction: 9999,
+      }),
+    ];
+
+    const result = (await handler({
+      queryParams: { q: "ali", categories: "contacts" },
+    })) as { results: { contacts: { id: string; lastInteraction: number }[] } };
+
+    expect(result.results.contacts).toHaveLength(1);
+    expect(result.results.contacts[0].lastInteraction).toBe(5000);
+  });
+
+  test("preserves searchContacts ordering deterministically", async () => {
+    searchContactsResult = [
+      makeContact({ id: "ct_a", displayName: "A", updatedAt: 300 }),
+      makeContact({ id: "ct_b", displayName: "B", updatedAt: 200 }),
+      makeContact({ id: "ct_c", displayName: "C", updatedAt: 100 }),
+    ];
+
+    const result = (await handler({
+      queryParams: { q: "x", categories: "contacts" },
+    })) as { results: { contacts: { id: string; lastInteraction: number }[] } };
+
+    expect(result.results.contacts.map((c) => c.id)).toEqual([
+      "ct_a",
+      "ct_b",
+      "ct_c",
+    ]);
+    expect(result.results.contacts.map((c) => c.lastInteraction)).toEqual([
+      300, 200, 100,
+    ]);
+  });
+});

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -25,10 +25,12 @@ interface StubConversation {
   handleSurfaceActionThrows?: Error;
   handleSurfaceUndoCalled?: boolean;
   handleSurfaceUndoThrows?: Error;
+  trustContext?: { trustClass: string; sourceChannel: string };
   surfaceActionCalls: Array<{
     surfaceId: string;
     actionId: string;
     data: unknown;
+    sourceActorPrincipalId?: string;
   }>;
 }
 
@@ -42,6 +44,47 @@ const findBySurfaceCalls: string[] = [];
 const getOrCreateCalls: string[] = [];
 const rawGetCalls: Array<{ sql: string; params: unknown[] }> = [];
 
+// Gateway guardian-delivery list (shared by the route's dev-bypass lookup and
+// the local-principal-trust mapper): null = unreachable, [] = no guardian.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
+let httpAuthDisabled = false;
+
+// Stub for the shared reset-drift helper. The route under test only consumes
+// its result (a guardian TrustContext or null); the gate itself is covered in
+// runtime/__tests__/guardian-vellum-migration.test.ts. Tests set
+// `mockReResolve` per case and read `reResolveCalls` to assert routing.
+const reResolveCalls: string[] = [];
+let mockReResolve: { trustClass: string; sourceChannel: string } | null = null;
+
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
+  peekCachedGuardianDelivery: () => mockGuardianList ?? undefined,
+  guardianForChannel: (
+    list: Array<Record<string, unknown>>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: (_channelType: string) => null,
+  findContactByAddress: () => null,
+}));
+
+mock.module("../../../config/env.js", () => ({
+  isHttpAuthDisabled: () => httpAuthDisabled,
+}));
+
+mock.module("../../guardian-vellum-migration.js", () => ({
+  reResolveTrustOnResetDrift: async (
+    incomingPrincipalId: string,
+    _sourceChannel: string,
+  ) => {
+    reResolveCalls.push(incomingPrincipalId);
+    return mockReResolve;
+  },
+}));
+
 mock.module("../../../daemon/conversation-registry.js", () => ({
   findConversation: (id: string) => {
     findConvCalls.push(id);
@@ -106,8 +149,14 @@ function makeStub(id: string): StubConversation {
       surfaceId: string,
       actionId: string,
       data: unknown,
+      sourceActorPrincipalId?: string,
     ) => {
-      stub.surfaceActionCalls.push({ surfaceId, actionId, data });
+      stub.surfaceActionCalls.push({
+        surfaceId,
+        actionId,
+        data,
+        sourceActorPrincipalId,
+      });
       if (stub.handleSurfaceActionThrows) throw stub.handleSurfaceActionThrows;
       return stub.handleSurfaceActionResult;
     },
@@ -115,6 +164,9 @@ function makeStub(id: string): StubConversation {
       stub.handleSurfaceUndoCalled = true;
       if (stub.handleSurfaceUndoThrows) throw stub.handleSurfaceUndoThrows;
     },
+    setTrustContext: (ctx: { trustClass: string; sourceChannel: string }) => {
+      stub.trustContext = ctx;
+    },
   });
   return stub;
 }
@@ -132,6 +184,10 @@ beforeEach(() => {
   findBySurfaceCalls.length = 0;
   getOrCreateCalls.length = 0;
   rawGetCalls.length = 0;
+  mockGuardianList = [];
+  httpAuthDisabled = false;
+  reResolveCalls.length = 0;
+  mockReResolve = null;
 });
 
 // ---------------------------------------------------------------------------
@@ -310,6 +366,50 @@ describe("triggerSurfaceAction handler", () => {
     expect(rawGetCalls[0]!.params).toEqual([`%"surfaceId":"\\%"%`]);
   });
 
+  test("threads x-vellum-actor-principal-id into handleSurfaceAction", async () => {
+    const live = makeStub("conv-principal");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-p", actionId: "act-p" },
+      headers: { "x-vellum-actor-principal-id": "principal-committer" },
+    });
+
+    expect(live.surfaceActionCalls).toEqual([
+      {
+        surfaceId: "surf-p",
+        actionId: "act-p",
+        data: undefined,
+        sourceActorPrincipalId: "principal-committer",
+      },
+    ]);
+  });
+
+  test("resolves dev-bypass to the guardian principal before threading the turn", async () => {
+    httpAuthDisabled = true;
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-dev-thread");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-dt", actionId: "act-dt" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    // dev-bypass is translated so the surface turn matches the SSE host-proxy
+    // client's registered guardian principal (CU/app-control same-actor check).
+    expect(live.surfaceActionCalls).toEqual([
+      {
+        surfaceId: "surf-dt",
+        actionId: "act-dt",
+        data: undefined,
+        sourceActorPrincipalId: GUARDIAN_PRINCIPAL,
+      },
+    ]);
+  });
+
   test("propagates accepted=false rejection as BadRequestError", async () => {
     const live = makeStub("conv-reject");
     live.handleSurfaceActionResult = {
@@ -335,6 +435,120 @@ describe("triggerSurfaceAction handler", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Trust context resolution
+// ---------------------------------------------------------------------------
+
+const GUARDIAN_PRINCIPAL = "principal-guardian";
+// Daemon-minted vellum-principal-* ids: the DB-reset drift signature. The
+// gateway rebinds to a fresh id while the client still holds a JWT for the old.
+const VELLUM_PRINCIPAL_OLD = "vellum-principal-old";
+const VELLUM_PRINCIPAL_NEW = "vellum-principal-new";
+
+function guardianDelivery(principalId: string): Record<string, unknown> {
+  return {
+    channelType: "vellum",
+    contactId: "contact-1",
+    principalId,
+    address: "guardian-address",
+    externalChatId: "guardian-chat",
+    status: "active",
+  };
+}
+
+// A guardian TrustContext the stubbed helper hands back on a recovered drift.
+function guardianCtx(): { trustClass: string; sourceChannel: string } {
+  return { trustClass: "guardian", sourceChannel: "vellum" };
+}
+
+describe("triggerSurfaceAction trust context", () => {
+  test("guardian principal → guardian from the gateway binding, helper not called", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-guardian");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-g", actionId: "act-g" },
+      headers: { "x-vellum-actor-principal-id": GUARDIAN_PRINCIPAL },
+    });
+
+    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(live.trustContext?.sourceChannel).toBe("vellum");
+    // First-pass resolve already granted guardian, so the drift helper is skipped.
+    expect(reResolveCalls).toEqual([]);
+  });
+
+  test("unknown principal: helper consulted, null result stays unknown (fail closed)", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    mockReResolve = null;
+    const live = makeStub("conv-unknown");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-u", actionId: "act-u" },
+      headers: { "x-vellum-actor-principal-id": VELLUM_PRINCIPAL_OLD },
+    });
+
+    expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
+    expect(live.trustContext?.trustClass).toBe("unknown");
+  });
+
+  test("reset drift: helper returns guardian → route adopts it", async () => {
+    mockGuardianList = [guardianDelivery(VELLUM_PRINCIPAL_NEW)];
+    mockReResolve = guardianCtx();
+    const live = makeStub("conv-drift");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-d", actionId: "act-d" },
+      headers: { "x-vellum-actor-principal-id": VELLUM_PRINCIPAL_OLD },
+    });
+
+    expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
+    expect(live.trustContext?.trustClass).toBe("guardian");
+  });
+
+  test("dev-bypass resolves the real guardian principal from the gateway, helper not called", async () => {
+    httpAuthDisabled = true;
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-dev");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-dev", actionId: "act-dev" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    // The synthetic dev-bypass principal is translated to the real guardian,
+    // yielding a guardian trust context without consulting the drift helper.
+    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(reResolveCalls).toEqual([]);
+  });
+
+  test("dev-bypass with an empty gateway: helper null result → unknown (fail closed)", async () => {
+    httpAuthDisabled = true;
+    // The gateway has no active binding, so dev-bypass cannot translate to a
+    // real guardian; the first-pass resolve is unknown and the helper, returning
+    // null, leaves trust unknown.
+    mockGuardianList = [];
+    mockReResolve = null;
+    const live = makeStub("conv-dev-fallback");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-devf", actionId: "act-devf" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    expect(live.trustContext?.trustClass).toBe("unknown");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // undoSurfaceAction
 // ---------------------------------------------------------------------------

package/src/runtime/routes/browser-routes.ts

@@ -92,7 +92,7 @@ async function handleBrowserExecute({
   // register with (dev-bypass otherwise mismatches).
   const headerActor =
     headers["x-vellum-actor-principal-id"]?.trim() || undefined;
-  const sourceActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+  const sourceActorPrincipalId = await resolveActorPrincipalIdForLocalGuardian(
     conversation?.getTurnActorPrincipalId() ?? headerActor,
   );
 

package/src/runtime/routes/channel-verification-routes.ts

@@ -179,7 +179,7 @@ export async function handleCreateVerificationSession({
   }
 
   // Inbound challenge path
-  const result = createInboundChallenge(channel, rebind, conversationId);
+  const result = await createInboundChallenge(channel, rebind, conversationId);
   if (!result.success) {
     throw new BadRequestError(
       (result as { message?: string }).message ??
@@ -192,12 +192,12 @@ export async function handleCreateVerificationSession({
 /**
  * GET /v1/channel-verification-sessions/status
  */
-function handleGetVerificationStatus({
+async function handleGetVerificationStatus({
   queryParams = {},
   body = {},
 }: RouteHandlerArgs) {
   const channel = (queryParams.channel ?? (body as Record<string, unknown>).channel) as ChannelId | undefined;
-  return getVerificationStatus(channel);
+  return await getVerificationStatus(channel);
 }
 
 /**

package/src/runtime/routes/contact-routes.ts

@@ -17,8 +17,6 @@ import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
 import { z } from "zod";
 
 import {
-  getAssistantContactMetadata,
-  getContact,
   listContacts,
   mergeContacts,
   searchContacts,
@@ -139,9 +137,10 @@ const contactSchema = z.object({
 
 /**
  * Relay a non-search contact list read to the gateway (source of truth for ACL
- * fields), falling back to the assistant DB on IPC failure. Shared by the GET
- * `contacts` list and the `search_contacts` no-filter case so both serve
- * gateway-sourced data consistently.
+ * fields). Shared by the GET `contacts` list and the `search_contacts`
+ * no-filter case so both serve gateway-sourced data consistently. Fail-closed:
+ * a relay failure surfaces as an error rather than reading ACL from the
+ * assistant DB.
  */
 async function relayListContacts(
   limit: number,
@@ -158,15 +157,7 @@ async function relayListContacts(
       contacts: contacts.map(prepareContactResponse),
     };
   } catch (err) {
-    log.warn(
-      { err },
-      "relayListContacts: gateway relay failed; falling back to assistant DB",
-    );
-    const contacts = listContacts(limit, role);
-    return {
-      ok: true,
-      contacts: contacts.map(prepareContactResponse),
-    };
+    rethrowGatewayError(err);
   }
 }
 
@@ -240,25 +231,10 @@ export async function handleGetContact(contactId: string) {
       assistantMetadata: assistantMetadata ?? undefined,
     };
   } catch (err) {
-    // A clean not-found is a real 404 — don't fall back or mask it.
+    // A clean not-found is a real 404. Any other relay failure fails closed
+    // rather than reading ACL from the assistant DB.
     if (err instanceof NotFoundError) throw err;
-    log.warn(
-      { err, contactId },
-      "handleGetContact: gateway relay failed; falling back to assistant DB",
-    );
-    const contact = getContact(contactId);
-    if (!contact) {
-      throw new NotFoundError(`Contact "${contactId}" not found`);
-    }
-    const assistantMeta =
-      contact.contactType === "assistant"
-        ? getAssistantContactMetadata(contact.id)
-        : undefined;
-    return {
-      ok: true,
-      contact: prepareContactResponse(contact),
-      assistantMetadata: assistantMeta ?? undefined,
-    };
+    rethrowGatewayError(err);
   }
 }