@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/runtime/routes/channel-route-shared.ts

@@ -3,10 +3,11 @@
  */
 import type { ChannelId } from "../../channels/types.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
-import type {
-  ApprovalAction,
-  ApprovalDecisionResult,
-  ApprovalUIMetadata,
+import {
+  type ApprovalAction,
+  type ApprovalDecisionResult,
+  type ApprovalUIMetadata,
+  isApprovalAction,
 } from "../channel-approval-types.js";
 
 /** Canonicalize assistantId for channel ingress paths. */
@@ -35,11 +36,6 @@ export function requiredDecisionKeywords(
 // Callback data parser — format: "apr:<requestId>:<action>"
 // ---------------------------------------------------------------------------
 
-const VALID_ACTIONS: ReadonlySet<string> = new Set<string>([
-  "approve_once",
-  "reject",
-]);
-
 /** Map legacy callback actions to canonical ones for in-flight buttons. */
 const LEGACY_CALLBACK_MAP: Record<string, string> = {
   approve_10m: "approve_once",
@@ -52,11 +48,15 @@ export function parseCallbackData(
   sourceChannel?: string,
 ): ApprovalDecisionResult | null {
   const parts = data.split(":");
-  if (parts.length < 3 || parts[0] !== "apr") return null;
+  if (parts.length < 3 || parts[0] !== "apr") {
+    return null;
+  }
   const requestId = parts[1];
   const rawAction = parts.slice(2).join(":");
   const action = LEGACY_CALLBACK_MAP[rawAction] ?? rawAction;
-  if (!requestId || !VALID_ACTIONS.has(action)) return null;
+  if (!requestId || !isApprovalAction(action)) {
+    return null;
+  }
   const source =
     sourceChannel === "whatsapp"
       ? ("whatsapp_button" as const)
@@ -65,7 +65,7 @@ export function parseCallbackData(
         : sourceChannel === "vellum"
           ? ("vellum_surface" as const)
           : ("telegram_button" as const);
-  return { action: action as ApprovalAction, source, requestId };
+  return { action, source, requestId };
 }
 
 // ---------------------------------------------------------------------------
@@ -93,10 +93,14 @@ const REACTION_EMOJI_MAP: ReadonlyMap<string, ApprovalAction> = new Map([
 export function parseReactionCallbackData(
   data: string,
 ): ApprovalDecisionResult | null {
-  if (!data.startsWith("reaction:")) return null;
+  if (!data.startsWith("reaction:")) {
+    return null;
+  }
   const emoji = data.slice("reaction:".length);
   const action = REACTION_EMOJI_MAP.get(emoji);
-  if (!action) return null;
+  if (!action) {
+    return null;
+  }
   return { action, source: "slack_reaction" };
 }
 

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

@@ -14,9 +14,6 @@
  *   inbound code-match path (`gateway/src/verification/text-verification.ts`).
  * - The revoke/downgrade OUTCOME is relayed from the daemon via
  *   `ipcCallPersistent("mark_channel_revoked", …)` to `ContactStore.markChannelRevoked`.
- * - The `mark_channel_verified` IPC method exists as the daemon/CLI relay surface (symmetric with
- *   `mark_channel_revoked`) but has no caller: the trusted-contact CLI path sends codes only, and the
- *   outcome arrives via the inbound code-match path.
  */
 
 import { z } from "zod";

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

@@ -8,6 +8,11 @@
  * they don't shadow more-specific sub-paths like contacts/invites.
  */
 
+import {
+  RedeemInviteByTokenRequestSchema,
+  RedeemVoiceInviteRequestSchema,
+} from "@vellumai/gateway-client";
+import type { ContactRead } from "@vellumai/gateway-client/gateway-ipc-contracts";
 import {
   GetContactIpcResponseSchema,
   ListContactsIpcResponseSchema,
@@ -22,14 +27,19 @@ import {
   searchContacts,
 } from "../../contacts/contact-store.js";
 import { getGuardianContactIds } from "../../contacts/guardian-contact-reader.js";
-import type { ContactRole, ContactType } from "../../contacts/types.js";
+import type {
+  ContactChannel,
+  ContactRole,
+  ContactType,
+  ContactWithChannels,
+} from "../../contacts/types.js";
 import { ipcCallPersistent } from "../../ipc/gateway-client.js";
 import { resolveGuardianName } from "../../prompts/user-reference.js";
 import { getLogger } from "../../util/logger.js";
-import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import {
-  redeemIngressInvite,
-  redeemVoiceInviteCode,
+  composeInvitePresentation,
+  resolveInviteGuardianName,
   triggerInviteCall,
 } from "../invite-service.js";
 import { BadRequestError, NotFoundError, RouteError } from "./errors.js";
@@ -147,9 +157,14 @@ function isContactType(value: string): value is ContactType {
 // (search / contactType) omit them, so they are `.optional()`. Contact-level
 // `role` is gateway-sourced: relayed reads trust the role on the `ContactRead`,
 // while daemon-native reads derive it from the gateway guardian id set at the
-// serve layer (see prepareContactResponse). INFO telemetry
-// (lastSeenAt/interactionCount/lastInteraction) is locally hydrated on every
-// read path and stays required.
+// serve layer (see prepareContactResponse). Interaction telemetry
+// (lastSeenAt/interactionCount/lastInteraction) is gateway-owned: relayed reads
+// carry it directly, and daemon-native reads batch-hydrate it from the gateway
+// (see hydrateTelemetryFromGateway). On a gateway fail-soft the count
+// `interactionCount` defaults to 0 (never served as null, so callers render a
+// real number); the `lastSeenAt`/`lastInteraction` timestamps degrade to null.
+// The timestamp fields stay `.nullable()`; `interactionCount` is kept nullable
+// defensively for the relay path, but is never emitted null.
 const contactChannelSchema = z.object({
   id: z.string(),
   contactId: z.string(),
@@ -163,7 +178,7 @@ const contactChannelSchema = z.object({
   verifiedAt: z.number().nullable().optional(),
   verifiedVia: z.string().nullable().optional(),
   lastSeenAt: z.number().nullable(),
-  interactionCount: z.number(),
+  interactionCount: z.number().nullable(),
   lastInteraction: z.number().nullable(),
   revokedReason: z.string().nullable().optional(),
   blockedReason: z.string().nullable().optional(),
@@ -176,7 +191,7 @@ const contactSchema = z.object({
   notes: z.string().nullable().optional(),
   contactType: z.enum(["human", "assistant"]),
   lastInteraction: z.number().nullable().optional(),
-  interactionCount: z.number(),
+  interactionCount: z.number().nullable(),
   createdAt: z.number(),
   updatedAt: z.number(),
   channels: z.array(contactChannelSchema),
@@ -211,6 +226,97 @@ async function relayListContacts(limit: number, role: ContactRole | undefined) {
   }
 }
 
+/**
+ * A daemon-native contact read whose gateway-owned interaction telemetry has
+ * been overlaid. `interactionCount` is a count, so it defaults to 0 on the
+ * gateway fail-soft/id-miss path (matching the gateway's NOT NULL DEFAULT 0
+ * column) — consumers never see `null` and render a real number. The
+ * `lastSeenAt`/`lastInteraction` timestamps stay nullable: a "never" timestamp
+ * is legitimately absent.
+ */
+type ContactWithGatewayTelemetry = Omit<ContactWithChannels, "channels"> & {
+  interactionCount: number;
+  lastInteraction: number | null;
+  channels: Array<
+    ContactChannel & {
+      lastSeenAt: number | null;
+      interactionCount: number;
+      lastInteraction: number | null;
+    }
+  >;
+};
+
+/**
+ * Key channels by (type, lower(address)) for the id-miss telemetry fallback.
+ * Matches the gateway's UNIQUE(type, address) NOCASE collation; the NUL
+ * delimiter cannot appear in either field, so keys never collide.
+ */
+function channelKey(type: string, address: string): string {
+  return `${type}\u0000${address.toLowerCase()}`;
+}
+
+/**
+ * Overlay gateway-owned interaction telemetry onto daemon-native contact reads
+ * (search / contactType-filtered), which bypass the gateway list relay. The
+ * daemon still owns the FILTERING (gateway-native search/contactType is
+ * design-blocked), but telemetry (contact + channel
+ * interactionCount/lastInteraction, channel lastSeenAt) is gateway-owned — so
+ * batch-fetch it via `contacts_list_rich` keyed by the filtered id set and
+ * overlay it, keeping the local assistant-DB aggregation out of the served
+ * payload. Fail-soft: if the gateway read fails or omits a contact, its
+ * interaction counts degrade to 0 and its timestamps to null rather than
+ * falling back to the local assistant-DB aggregation.
+ */
+async function hydrateTelemetryFromGateway(
+  contacts: ContactWithChannels[],
+): Promise<ContactWithGatewayTelemetry[]> {
+  if (contacts.length === 0) return [];
+
+  const gatewayById = new Map<string, ContactRead>();
+  try {
+    const result = await ipcCallPersistent("contacts_list_rich", {
+      ids: contacts.map((c) => c.id),
+    });
+    const { contacts: rich } = ListContactsIpcResponseSchema.parse(result);
+    for (const c of rich) gatewayById.set(c.id, c);
+  } catch (err) {
+    log.warn(
+      { err },
+      "hydrateTelemetryFromGateway: gateway telemetry read failed; serving 0 counts / null timestamps",
+    );
+  }
+
+  return contacts.map((c) => {
+    const gw = gatewayById.get(c.id);
+    const gwChannelById = new Map(
+      (gw?.channels ?? []).map((ch) => [ch.id, ch]),
+    );
+    // Local channel UUIDs can diverge from the gateway's for the same
+    // (type, address) (legacy pre-alignment channels), so an id-miss falls back
+    // to a (type, lower(address)) match — mirroring the gateway's
+    // overlayAclOntoContacts. UNIQUE(type, address) collates NOCASE gateway-side.
+    const gwChannelByTypeAddress = new Map(
+      (gw?.channels ?? []).map((ch) => [channelKey(ch.type, ch.address), ch]),
+    );
+    return {
+      ...c,
+      interactionCount: gw?.interactionCount ?? 0,
+      lastInteraction: gw?.lastInteraction ?? null,
+      channels: c.channels.map((ch) => {
+        const gwCh =
+          gwChannelById.get(ch.id) ??
+          gwChannelByTypeAddress.get(channelKey(ch.type, ch.address));
+        return {
+          ...ch,
+          lastSeenAt: gwCh?.lastSeenAt ?? null,
+          interactionCount: gwCh?.interactionCount ?? 0,
+          lastInteraction: gwCh?.lastInteraction ?? null,
+        };
+      }),
+    };
+  });
+}
+
 export async function handleListContacts(queryParams: Record<string, string>) {
   const limit = Number(queryParams.limit ?? 50);
   const role = (queryParams.role as ContactRole) || undefined;
@@ -234,15 +340,20 @@ export async function handleListContacts(queryParams: Record<string, string>) {
     log.debug(
       "handleListContacts: search served daemon-native (gateway-native search is design-blocked)",
     );
-    const contacts = searchContacts({
-      query,
-      channelAddress,
-      channelType,
-      contactType,
-      limit,
-    });
-    // Daemon-native read: role is the neutral default, so derive it.
-    const guardianIds = await getGuardianContactIds();
+    // Telemetry hydration and the guardian-id read (for role derivation) both
+    // hit the gateway and are independent — run them concurrently.
+    const [contacts, guardianIds] = await Promise.all([
+      hydrateTelemetryFromGateway(
+        searchContacts({
+          query,
+          channelAddress,
+          channelType,
+          contactType,
+          limit,
+        }),
+      ),
+      getGuardianContactIds(),
+    ]);
     return {
       ok: true,
       contacts: contacts.map((c) => prepareContactResponse(c, guardianIds)),
@@ -257,9 +368,12 @@ export async function handleListContacts(queryParams: Record<string, string>) {
     log.debug(
       "handleListContacts: contactType-filtered read served daemon-native (gateway-native contactType filtering is design-blocked, pending ACL classification)",
     );
-    const contacts = listContacts(limit, contactType);
-    // Daemon-native read: role is the neutral default, so derive it.
-    const guardianIds = await getGuardianContactIds();
+    // Telemetry hydration and the guardian-id read (for role derivation) both
+    // hit the gateway and are independent — run them concurrently.
+    const [contacts, guardianIds] = await Promise.all([
+      hydrateTelemetryFromGateway(listContacts(limit, contactType)),
+      getGuardianContactIds(),
+    ]);
     return {
       ok: true,
       contacts: contacts.map((c) => prepareContactResponse(c, guardianIds)),
@@ -296,17 +410,10 @@ export async function handleGetContact(contactId: string) {
 // Invite handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
 
-// The gateway owns the canonical invite write path. These CLI handlers relay
-// to the gateway IPC methods via `ipcCallPersistent`; the assistant DB is
-// written only by the gateway. (Redemption stays daemon-local — see the redeem route.)
-
-// The invite-CREATE relay needs a generous timeout: the gateway's `invites_mint`
-// handler calls `createIngressInvite` → `generateInviteInstruction`, which can spend
-// up to GENERATION_TIMEOUT_MS (~5s) waiting on an LLM before falling back. The default
-// 5s persistent-IPC timeout can fire mid-mint, so the caller sees a spurious failure
-// even though the gateway is still writing the invite. 30s safely exceeds the inner
-// ~5s fallback plus IPC overhead on both nested hops. (List/revoke keep the default.)
-const INVITE_CREATE_RELAY_TIMEOUT_MS = 30_000;
+// The gateway owns the canonical invite lifecycle: mint, list, revoke, and
+// redemption. These CLI handlers relay via `ipcCallPersistent`; the daemon
+// then layers the presentation fields (share link, LLM guardian instruction,
+// channel handle) onto the gateway's one-time create payload.
 
 export async function handleListInvites({
   queryParams = {},
@@ -325,29 +432,41 @@ export async function handleListInvites({
 }
 
 export async function handleCreateInvite({ body = {} }: RouteHandlerArgs) {
+  const contactId = body.contactId as string;
+  const sourceChannel = body.sourceChannel as string | undefined;
+  // The guardian display label on voice invites is daemon-resolved and passed
+  // through to the gateway, which stores it and never interprets it.
+  const guardianName =
+    sourceChannel === "phone" ? resolveInviteGuardianName() : undefined;
+  let result: { invite: Record<string, unknown>; rawToken?: string };
   try {
-    const result = (await ipcCallPersistent(
-      "invites_create",
-      {
-        contactId: body.contactId as string,
-        sourceChannel: body.sourceChannel as string | undefined,
-        note: body.note as string | undefined,
-        maxUses: body.maxUses as number | undefined,
-        expiresInMs: body.expiresInMs as number | undefined,
-        expectedExternalUserId: body.expectedExternalUserId as
-          | string
-          | undefined,
-      },
-      INVITE_CREATE_RELAY_TIMEOUT_MS,
-    )) as { invite: Record<string, unknown>; rawToken?: string };
-    return {
-      ok: true,
-      invite: result.invite,
-      ...(result.rawToken ? { rawToken: result.rawToken } : {}),
-    };
+    result = (await ipcCallPersistent("invites_create", {
+      contactId,
+      sourceChannel,
+      note: body.note as string | undefined,
+      maxUses: body.maxUses as number | undefined,
+      expiresInMs: body.expiresInMs as number | undefined,
+      expectedExternalUserId: body.expectedExternalUserId as
+        | string
+        | undefined,
+      ...(guardianName ? { guardianName } : {}),
+      ...(typeof body.sourceConversationId === "string"
+        ? { sourceConversationId: body.sourceConversationId }
+        : {}),
+    })) as { invite: Record<string, unknown>; rawToken?: string };
   } catch (err) {
     rethrowGatewayError(err);
   }
+  const invite = await composeInvitePresentation({
+    contactId,
+    invite: result.invite,
+    rawToken: result.rawToken,
+  });
+  return {
+    ok: true,
+    invite,
+    ...(result.rawToken ? { rawToken: result.rawToken } : {}),
+  };
 }
 
 export async function handleRevokeInvite({
@@ -366,58 +485,69 @@ export async function handleRevokeInvite({
 /**
  * Redeem a voice invite code.
  *
- * Backs the HTTP `invites_redeem` route (voice path) and the IPC-only
- * `invites_redeem_voice` method. Wraps the identity-bound
- * `redeemVoiceInviteCode` path.
+ * Backs the HTTP `invites_redeem` route (voice path). Parses the body with
+ * the shared `RedeemVoiceInviteRequestSchema` wire contract (plus the
+ * daemon-specific `assistantId` passthrough) and relays to the gateway's
+ * `invites_redeem` IPC — the gateway redemption engine owns validation, the
+ * atomic claim, and the ACL write. Fail-closed: a gateway relay failure
+ * surfaces as an error; there is no local redemption fallback.
  */
-export async function handleRedeemVoiceInvite({ body = {} }: RouteHandlerArgs) {
-  const callerExternalUserId = body.callerExternalUserId as string | undefined;
-  const code = body.code as string | undefined;
-
-  if (!callerExternalUserId || !code) {
+async function handleRedeemVoiceInvite({ body = {} }: RouteHandlerArgs) {
+  const parsed = RedeemVoiceInviteRequestSchema.safeParse(body);
+  if (!parsed.success) {
     throw new BadRequestError("callerExternalUserId and code are required");
   }
 
-  const result = await redeemVoiceInviteCode({
-    assistantId: body.assistantId as string | undefined,
-    callerExternalUserId,
-    sourceChannel: "phone",
-    code,
-  });
-
-  if (!result.ok) {
-    throw new BadRequestError(result.reason);
+  try {
+    return (await ipcCallPersistent("invites_redeem", {
+      ...parsed.data,
+      ...(typeof body.assistantId === "string"
+        ? { assistantId: body.assistantId }
+        : {}),
+    })) as { ok: true; type: string; memberId: string; inviteId?: string };
+  } catch (err) {
+    rethrowGatewayError(err);
   }
+}
 
-  return {
-    ok: true,
-    type: result.type,
-    memberId: result.memberId,
-    ...(result.type === "redeemed" ? { inviteId: result.inviteId } : {}),
-  };
+/** Map a token-branch schema failure to the stable redeem error messages. */
+function redeemTokenIssueMessage(error: z.ZodError): string {
+  for (const field of ["token", "sourceChannel"] as const) {
+    if (error.issues.some((issue) => issue.path[0] === field)) {
+      return `${field} is required`;
+    }
+  }
+  return error.issues[0]?.message ?? "Invalid redemption request";
 }
 
 /**
  * Redeem a token invite.
  *
- * Backs the HTTP `invites_redeem` route (token path) and the IPC-only
- * `invites_redeem_token` method. Wraps the generic `redeemIngressInvite`
- * token path.
+ * Backs the HTTP `invites_redeem` route (token path). Parses the body with
+ * the shared `RedeemInviteByTokenRequestSchema` wire contract and relays the
+ * parsed request verbatim — including the sender identity fields
+ * (`displayName` / `username`) the gateway engine stamps onto the new member —
+ * to the gateway's `invites_redeem` IPC. The gateway redemption engine owns
+ * validation, the atomic claim, and the ACL write. Fail-closed: a gateway
+ * relay failure surfaces as an error; there is no local redemption fallback.
  */
-export async function handleRedeemTokenInvite({ body = {} }: RouteHandlerArgs) {
-  const result = await redeemIngressInvite({
-    token: body.token as string | undefined,
-    externalUserId: body.externalUserId as string | undefined,
-    externalChatId: body.externalChatId as string | undefined,
-    sourceChannel: body.sourceChannel as string | undefined,
-  });
+async function handleRedeemTokenInvite({ body = {} }: RouteHandlerArgs) {
+  const parsed = RedeemInviteByTokenRequestSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(redeemTokenIssueMessage(parsed.error));
+  }
 
-  if (!result.ok) {
-    throw new BadRequestError(result.error);
+  try {
+    // The `type` is surfaced so callers can tell a real redeem apart from an
+    // `already_member` no-op (which consumes no invite use).
+    return (await ipcCallPersistent("invites_redeem", parsed.data)) as {
+      ok: true;
+      invite: Record<string, unknown>;
+      type: string;
+    };
+  } catch (err) {
+    rethrowGatewayError(err);
   }
-  // Surface the redemption `type` so the gateway can skip mirroring an
-  // `already_member` redeem (which consumes no invite use).
-  return { ok: true, invite: result.data.invite, type: result.data.type };
 }
 
 export async function handleRedeemInvite(args: RouteHandlerArgs) {
@@ -428,14 +558,17 @@ export async function handleRedeemInvite(args: RouteHandlerArgs) {
   return handleRedeemTokenInvite(args);
 }
 
-// Stays daemon-local by design (like invites_redeem): the gateway's call path
-// validates its row then delegates the actual provider call to THIS handler via
-// ipcCallAssistant("invites_trigger_call"). Relaying back would loop
-// gateway→assistant→gateway. The provider call is a daemon capability.
-export async function handleTriggerInviteCall({
-  pathParams = {},
-}: RouteHandlerArgs) {
-  const result = await triggerInviteCall(pathParams.id);
+// Stays daemon-local by design (like invites_redeem): the gateway validates
+// its canonical invite row, then delegates the actual provider call to THIS
+// handler via ipcCallAssistant("invites_trigger_call") with the resolved call
+// fields in the body. Relaying back would loop gateway→assistant→gateway.
+// The provider call is a daemon capability.
+export async function handleTriggerInviteCall({ body = {} }: RouteHandlerArgs) {
+  const result = await triggerInviteCall({
+    phoneNumber: body.phoneNumber as string | undefined,
+    friendName: body.friendName as string | null | undefined,
+    guardianName: body.guardianName as string | null | undefined,
+  });
   if (!result.ok) {
     throw new BadRequestError(result.error);
   }
@@ -561,6 +694,10 @@ export const ROUTES: RouteDefinition[] = [
         .string()
         .describe("Expected user ID (E.164 for phone)")
         .optional(),
+      sourceConversationId: z
+        .string()
+        .describe("Conversation the invite was created from (opaque)")
+        .optional(),
     }),
     responseBody: z.object({
       ok: z.boolean(),
@@ -577,9 +714,9 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
   {
-    // Stays daemon-local by design: redemption is an inbound-channel path (not
-    // a CLI ACL surface), and the assistant redemption service already claims
-    // the gateway row by id via record_invite_redemption — relaying would loop.
+    // Relays to the gateway `invites_redeem` IPC: the gateway redemption
+    // engine is the single lifecycle authority (validation, atomic claim,
+    // ACL upsert). Fail-closed when the gateway is unreachable.
     operationId: "invites_redeem",
     endpoint: "contacts/invites/redeem",
     method: "POST",
@@ -592,15 +729,33 @@ export const ROUTES: RouteDefinition[] = [
     description: "Redeem an invite by token or voice code.",
     tags: ["contacts"],
     requestBody: z.object({
-      token: z.string().describe("Invite token (token-based redemption)"),
-      code: z.string().describe("Voice code (voice-code redemption)"),
+      token: z
+        .string()
+        .optional()
+        .describe("Invite token (token-based redemption)"),
+      code: z.string().optional().describe("Voice code (voice-code redemption)"),
       callerExternalUserId: z
         .string()
+        .optional()
         .describe("Caller E.164 phone (voice-code)"),
-      externalUserId: z.string().describe("External user ID (token-based)"),
-      externalChatId: z.string().describe("External chat ID (token-based)"),
-      sourceChannel: z.string().describe("Source channel (token-based)"),
-      assistantId: z.string().describe("Assistant ID (voice-code)"),
+      externalUserId: z
+        .string()
+        .optional()
+        .describe("External user ID (token-based)"),
+      externalChatId: z
+        .string()
+        .optional()
+        .describe("External chat ID (token-based)"),
+      sourceChannel: z
+        .string()
+        .optional()
+        .describe("Source channel (token-based)"),
+      displayName: z
+        .string()
+        .optional()
+        .describe("Sender display name (token-based)"),
+      username: z.string().optional().describe("Sender username (token-based)"),
+      assistantId: z.string().optional().describe("Assistant ID (voice-code)"),
     }),
     responseBody: z.object({
       ok: z.boolean(),
@@ -639,14 +794,33 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_trigger_call",
     endpoint: "contacts/invites/:id/call",
     method: "POST",
+    // Gateway-only: the handler dials whatever number is in the body — the
+    // invite validation in the gateway's triggerInviteCallNative is the sole
+    // gate, so an actor-reachable policy would be an arbitrary-dial primitive.
     policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
     },
     handler: handleTriggerInviteCall,
     summary: "Trigger invite call",
-    description: "Trigger an outbound call for a phone invite.",
+    description:
+      "Trigger an outbound call for a phone invite. Gateway-only: the gateway validates its canonical invite row and supplies the resolved call fields in the body.",
     tags: ["contacts"],
+    requestBody: z.object({
+      phoneNumber: z
+        .string()
+        .describe("E.164 number the invite call dials (invite's bound caller)"),
+      friendName: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Invitee display name for the call greeting"),
+      guardianName: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Guardian display label recorded on the invite"),
+    }),
     responseBody: z.object({
       ok: z.boolean(),
       callSid: z.string().describe("Call SID from the provider"),
@@ -706,11 +880,13 @@ export const ROUTES: RouteDefinition[] = [
       log.debug(
         "search_contacts: search served daemon-native (gateway-native search is design-blocked)",
       );
-      // Daemon-native read: role is the neutral default, so derive it.
-      const guardianIds = await getGuardianContactIds();
-      return searchContacts(parsed).map((c) =>
-        prepareContactResponse(c, guardianIds),
-      );
+      // Telemetry hydration and the guardian-id read (for role derivation) both
+      // hit the gateway and are independent — run them concurrently.
+      const [contacts, guardianIds] = await Promise.all([
+        hydrateTelemetryFromGateway(searchContacts(parsed)),
+        getGuardianContactIds(),
+      ]);
+      return contacts.map((c) => prepareContactResponse(c, guardianIds));
     },
   },
 
@@ -806,11 +982,16 @@ async function handleMergeContactsRoute(args: RouteHandlerArgs) {
 
   try {
     const contact = mergeContacts(keepId, mergeId);
-    // Daemon-native read (assistant DB): role is the neutral default, derive it.
-    const guardianIds = await getGuardianContactIds();
+    // Daemon-native read (assistant DB): telemetry is gateway-owned, so overlay
+    // it (fail-soft to null) and derive role from the guardian-id set. Both hit
+    // the gateway and are independent — run them concurrently.
+    const [[hydrated], guardianIds] = await Promise.all([
+      hydrateTelemetryFromGateway([contact]),
+      getGuardianContactIds(),
+    ]);
     return {
       ok: true,
-      contact: prepareContactResponse(contact, guardianIds),
+      contact: prepareContactResponse(hydrated, guardianIds),
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/runtime/routes/conversation-list-routes.ts

@@ -117,6 +117,12 @@ export const conversationSummarySchema = z.object({
    */
   surfacedAt: z.number().optional(),
   inferenceProfile: z.string().optional(),
+  /**
+   * Plugin-id list scoping this chat to a subset of installed plugins.
+   * Absent when there is no per-chat restriction (default: all enabled
+   * plugins); an explicit `[]` means the user cleared all optional plugins.
+   */
+  enabledPlugins: z.array(z.string()).nullable().optional(),
   /**
    * True when the agent loop is currently mid-turn for this conversation.
    * Mirrors the in-memory `Conversation.isProcessing()` flag on the daemon