@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/runtime/invite-redemption-service.ts

@@ -10,6 +10,7 @@
 import type { ChannelId } from "../channels/types.js";
 import { findContactChannel, getContact } from "../contacts/contact-store.js";
 import { upsertContactChannel } from "../contacts/contacts-write.js";
+import { ipcCallPersistent } from "../ipc/gateway-client.js";
 import { getSqlite } from "../memory/db-connection.js";
 import {
   findActiveVoiceInvites,
@@ -20,8 +21,84 @@ import {
   recordInviteUse,
 } from "../memory/invite-store.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+import { getLogger } from "../util/logger.js";
 import { hashVoiceCode } from "../util/voice-code.js";
 
+const log = getLogger("invite-redemption-service");
+
+// ---------------------------------------------------------------------------
+// Gateway lifecycle bridge (shared by all redemption paths)
+// ---------------------------------------------------------------------------
+//
+// The assistant is the authority on token/code → invite resolution (it holds
+// the hashes and caller scoping). Once it has resolved the EXACT invite and
+// passed its own validation, it CLAIMS the gateway-canonical row — BY ID, which
+// is unambiguous — as the AUTHORITATIVE lifecycle gate BEFORE mutating its own
+// DB. `record_invite_redemption` atomically checks status="active" and consumes
+// the row, so there is no check-then-act window: a guardian revoke or a racing
+// redemption that consumes the gateway row first makes this claim fail, and the
+// assistant never mutates. This keeps the gateway invite row the lifecycle
+// source of truth across every redemption path (token + 6-digit channel
+// intercepts, voice relay, HTTP).
+
+/**
+ * Atomically CLAIM the gateway-canonical invite row for `inviteId`.
+ *
+ * This is the single authoritative gateway gate, performed BEFORE the assistant
+ * mutation. Returns a decision the caller maps to behavior:
+ *   - "claimed": the gateway row existed and was consumed (active → redeemed) →
+ *     proceed to the assistant mutation.
+ *   - "rejected": the gateway row EXISTS but was NOT consumable
+ *     (revoked / exhausted / expired / already redeemed in a race) → REJECT the
+ *     redemption WITHOUT mutating the assistant DB.
+ *   - "legacy": no gateway row exists (pre-migration assistant-only invite) →
+ *     proceed (the assistant stays authoritative). Logged at warn.
+ *   - "unavailable": the gateway IPC threw (gateway unreachable). FAIL-OPEN —
+ *     proceed; the assistant-side checks still apply. Logged loudly.
+ */
+async function claimGatewayRedemption(
+  inviteId: string,
+  redeemedBy: {
+    redeemedByExternalUserId?: string | null;
+    redeemedByExternalChatId?: string | null;
+  },
+): Promise<"claimed" | "rejected" | "legacy" | "unavailable"> {
+  try {
+    const res = (await ipcCallPersistent("record_invite_redemption", {
+      inviteId,
+      redeemedByExternalUserId: redeemedBy.redeemedByExternalUserId ?? null,
+      redeemedByExternalChatId: redeemedBy.redeemedByExternalChatId ?? null,
+    })) as { ok?: boolean; updated?: boolean; mirrored?: boolean } | null;
+
+    if (!res || typeof res !== "object") {
+      log.warn(
+        { inviteId, res },
+        "record_invite_redemption: gateway returned malformed response — failing open",
+      );
+      return "unavailable";
+    }
+    if (res.mirrored === false) {
+      log.warn(
+        { inviteId },
+        "record_invite_redemption: no gateway invite row — treating as legacy assistant-only invite",
+      );
+      return "legacy";
+    }
+    // mirrored === true: a gateway row exists. `updated` reflects whether the
+    // atomic status="active" claim consumed it.
+    return res.updated ? "claimed" : "rejected";
+  } catch (err) {
+    // FAIL-OPEN: availability > strict gating. The assistant-side validation
+    // (status/expiry/use-count/channel) still applies; we just couldn't claim
+    // the gateway-canonical row.
+    log.error(
+      { err, inviteId },
+      "record_invite_redemption: gateway claim unavailable — failing open (assistant-side checks still apply)",
+    );
+    return "unavailable";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Outcome type
 // ---------------------------------------------------------------------------
@@ -67,7 +144,7 @@ const STORE_ERROR_TO_REASON: Record<
 // redeemInvite
 // ---------------------------------------------------------------------------
 
-export function redeemInvite(params: {
+export async function redeemInvite(params: {
   rawToken: string;
   sourceChannel: string;
   externalUserId?: string;
@@ -75,7 +152,7 @@ export function redeemInvite(params: {
   displayName?: string;
   username?: string;
   assistantId?: string;
-}): InviteRedemptionOutcome {
+}): Promise<InviteRedemptionOutcome> {
   const {
     rawToken,
     sourceChannel,
@@ -156,6 +233,20 @@ export function redeemInvite(params: {
     return { ok: false, reason: "invalid_token" };
   }
 
+  // Authoritative gateway claim (by id — caller-scoped resolution already
+  // picked the exact invite). Consume the gateway-canonical row BEFORE mutating
+  // the assistant so a concurrent revoke/redemption that consumes it first
+  // rejects here, with no assistant mutation to roll back. No use is consumed
+  // for the already_member/blocked early returns above.
+  if (
+    (await claimGatewayRedemption(invite.id, {
+      redeemedByExternalUserId: externalUserId,
+      redeemedByExternalChatId: externalChatId,
+    })) === "rejected"
+  ) {
+    return { ok: false, reason: "invalid_token" };
+  }
+
   // Inactive member reactivation: when the user already has a member record
   // in a non-active state (revoked/pending), reactivate it via upsertContactChannel
   // and consume an invite use atomically. The fresh-member path below also
@@ -211,6 +302,13 @@ export function redeemInvite(params: {
       if (err === STALE_INVITE) {
         return { ok: false, reason: "invalid_token" };
       }
+      // Rare: the gateway claim already consumed the row but the assistant
+      // mutation failed — a recoverable wasted gateway use; no cross-process
+      // rollback is attempted.
+      log.error(
+        { err, inviteId: invite.id },
+        "redeemInvite: assistant mutation failed AFTER gateway claim consumed the row (wasted use)",
+      );
       throw err;
     }
 
@@ -267,6 +365,12 @@ export function redeemInvite(params: {
     if (err === STALE_INVITE_FRESH) {
       return { ok: false, reason: "invalid_token" };
     }
+    // Rare: gateway claim succeeded but the assistant mutation failed — a
+    // recoverable wasted gateway use; no cross-process rollback attempted.
+    log.error(
+      { err, inviteId: invite.id },
+      "redeemInvite: assistant mutation failed AFTER gateway claim consumed the row (wasted use)",
+    );
     throw err;
   }
 
@@ -298,12 +402,12 @@ export function redeemInvite(params: {
  * oracle attacks that could reveal which invites exist or which phone numbers
  * are bound.
  */
-export function redeemVoiceInviteCode(params: {
+export async function redeemVoiceInviteCode(params: {
   assistantId?: string;
   callerExternalUserId: string;
   sourceChannel: "phone";
   code: string;
-}): VoiceRedemptionOutcome {
+}): Promise<VoiceRedemptionOutcome> {
   const { callerExternalUserId, code } = params;
 
   if (!callerExternalUserId) {
@@ -378,6 +482,20 @@ export function redeemVoiceInviteCode(params: {
     return { ok: false, reason: "invalid_or_expired" };
   }
 
+  // Authoritative gateway claim (by id). The candidate was already resolved
+  // caller-scoped (expectedExternalUserId == caller), so the id is unambiguous
+  // even when two phone invites share a 6-digit code — this closes the
+  // colliding-code gap that a code-hash-only gateway gate left open. Consuming
+  // the gateway row here, before the assistant mutation, closes the TOCTOU
+  // window: a concurrent revoke/redemption rejects with no assistant mutation.
+  if (
+    (await claimGatewayRedemption(invite.id, {
+      redeemedByExternalUserId: callerExternalUserId,
+    })) === "rejected"
+  ) {
+    return { ok: false, reason: "invalid_or_expired" };
+  }
+
   // Atomic redemption: upsert member + consume invite use in a transaction
   const STALE_INVITE = Symbol("stale_invite");
   let memberId: string | undefined;
@@ -424,6 +542,12 @@ export function redeemVoiceInviteCode(params: {
     if (err === STALE_INVITE) {
       return { ok: false, reason: "invalid_or_expired" };
     }
+    // Rare: gateway claim succeeded but the assistant mutation failed — a
+    // recoverable wasted gateway use; no cross-process rollback attempted.
+    log.error(
+      { err, inviteId: invite.id },
+      "redeemVoiceInviteCode: assistant mutation failed AFTER gateway claim consumed the row (wasted use)",
+    );
     throw err;
   }
 
@@ -449,7 +573,7 @@ export function redeemVoiceInviteCode(params: {
  * Validation: active status, not expired, uses remaining, channel match.
  * On success: upserts/reactivates a member with status 'active', policy 'allow'.
  */
-export function redeemInviteByCode(params: {
+export async function redeemInviteByCode(params: {
   code: string;
   sourceChannel: string;
   externalUserId?: string;
@@ -457,7 +581,7 @@ export function redeemInviteByCode(params: {
   displayName?: string;
   username?: string;
   assistantId?: string;
-}): InviteRedemptionOutcome {
+}): Promise<InviteRedemptionOutcome> {
   const {
     code,
     sourceChannel,
@@ -530,6 +654,19 @@ export function redeemInviteByCode(params: {
     return { ok: false, reason: "invalid_token" };
   }
 
+  // Authoritative gateway claim (by id). Consume the gateway-canonical row
+  // before mutating the assistant, so a concurrent revoke/redemption that
+  // consumes it first rejects here with no assistant mutation to roll back. No
+  // use is consumed for the already_member/blocked early returns above.
+  if (
+    (await claimGatewayRedemption(invite.id, {
+      redeemedByExternalUserId: externalUserId,
+      redeemedByExternalChatId: externalChatId,
+    })) === "rejected"
+  ) {
+    return { ok: false, reason: "invalid_token" };
+  }
+
   // Inactive member reactivation: reactivate via upsertContactChannel and consume
   // an invite use atomically.
   if (existingChannel && !targetMismatch) {
@@ -577,6 +714,12 @@ export function redeemInviteByCode(params: {
       if (err === STALE_INVITE_REACTIVATE) {
         return { ok: false, reason: "invalid_token" };
       }
+      // Rare: gateway claim succeeded but the assistant mutation failed — a
+      // recoverable wasted gateway use; no cross-process rollback attempted.
+      log.error(
+        { err, inviteId: invite.id },
+        "redeemInviteByCode: assistant mutation failed AFTER gateway claim consumed the row (wasted use)",
+      );
       throw err;
     }
 
@@ -633,6 +776,12 @@ export function redeemInviteByCode(params: {
     if (err === STALE_INVITE_FRESH) {
       return { ok: false, reason: "invalid_token" };
     }
+    // Rare: gateway claim succeeded but the assistant mutation failed — a
+    // recoverable wasted gateway use; no cross-process rollback attempted.
+    log.error(
+      { err, inviteId: invite.id },
+      "redeemInviteByCode: assistant mutation failed AFTER gateway claim consumed the row (wasted use)",
+    );
     throw err;
   }
 

package/src/runtime/invite-service.ts

@@ -10,16 +10,14 @@
 
 import { startInviteCall } from "../calls/call-domain.js";
 import { isChannelId } from "../channels/types.js";
+import { getContact } from "../contacts/contact-store.js";
 import {
   createInvite,
   findById,
   findByTokenHash,
   hashToken,
   type IngressInvite,
-  type InviteStatus,
-  listInvites,
   markInviteExpired,
-  revokeInvite,
 } from "../memory/invite-store.js";
 import {
   DECLINED_BY_USER_SENTINEL,
@@ -43,6 +41,12 @@ import {
 // Response shapes — used by both HTTP routes and message handlers
 // ---------------------------------------------------------------------------
 
+/**
+ * Redemption outcome type surfaced to callers. `already_member` consumes no
+ * invite use, so the gateway must not mirror it into recordInviteRedemption.
+ */
+export type RedemptionType = "redeemed" | "already_member";
+
 export interface InviteResponseData {
   id: string;
   sourceChannel: string;
@@ -151,13 +155,11 @@ export async function createIngressInvite(params: {
   note?: string;
   maxUses?: number;
   expiresInMs?: number;
-  // Contact display name for personalizing invite instructions
-  contactName?: string;
-  // Voice invite parameters
+  // Voice invite parameters. Display metadata is no longer accepted from
+  // callers: the invitee's name is resolved from the bound contact's
+  // displayName at every read site (voice greeting, instructions), and the
+  // guardian label is resolved at runtime via resolveGuardianName().
   expectedExternalUserId?: string;
-  voiceCodeDigits?: number;
-  friendName?: string;
-  guardianName?: string;
   contactId: string;
 }): Promise<IngressResult<InviteResponseData>> {
   if (!params.sourceChannel) {
@@ -168,6 +170,13 @@ export async function createIngressInvite(params: {
     return { ok: false, error: "contactId is required for create" };
   }
 
+  // Resolve the bound contact's displayName as the canonical invitee name.
+  // The greeting and instruction copy use this rather than a free-text flag.
+  const boundContact = getContact(params.contactId);
+  const resolvedContactName =
+    boundContact?.displayName?.trim() || undefined;
+  const resolvedFirstName = resolvedContactName?.split(/\s+/)[0];
+
   // For voice invites: generate a one-time numeric code, hash it, and pass
   // the hash to the store. The plaintext code is included in the response
   // exactly once and never stored.
@@ -196,17 +205,13 @@ export async function createIngressInvite(params: {
           "expectedExternalUserId must be in E.164 format (e.g., +15551234567)",
       };
     }
-    if (typeof params.friendName !== "string" || !params.friendName.trim()) {
-      return { ok: false, error: "friendName is required for voice invites" };
-    }
-    effectiveGuardianName =
-      params.guardianName?.trim() || resolveGuardianName();
+    effectiveGuardianName = resolveGuardianName();
     if (
       !effectiveGuardianName ||
       effectiveGuardianName === DEFAULT_USER_REFERENCE ||
       effectiveGuardianName === DECLINED_BY_USER_SENTINEL
     ) {
-      return { ok: false, error: "guardianName is required for voice invites" };
+      effectiveGuardianName = undefined;
     }
     voiceCode = generateVoiceCode(6);
     voiceCodeHash = hashVoiceCode(voiceCode);
@@ -226,7 +231,10 @@ export async function createIngressInvite(params: {
           expectedExternalUserId: params.expectedExternalUserId,
           voiceCodeHash,
           voiceCodeDigits: 6,
-          friendName: params.friendName,
+          // Mirror the contact-resolved names into the legacy columns so
+          // outbound invite calls (which still read invite.friendName /
+          // invite.guardianName) keep working without a separate lookup.
+          friendName: resolvedContactName,
           guardianName: effectiveGuardianName,
         }
       : { inviteCodeHash }),
@@ -250,7 +258,7 @@ export async function createIngressInvite(params: {
     channelHandle = adapter ? await resolveAdapterHandle(adapter) : undefined;
     const share = buildSharePayload(params.sourceChannel, rawToken);
     guardianInstruction = await generateInviteInstruction({
-      contactName: params.contactName,
+      contactName: resolvedContactName,
       channelType: params.sourceChannel,
       channelHandle,
       hasShareUrl: !!share?.url,
@@ -258,8 +266,10 @@ export async function createIngressInvite(params: {
     });
   }
 
-  if (isVoice && params.friendName) {
-    guardianInstruction = `${params.friendName} will need this code when they answer. Share it with them first.`;
+  if (isVoice) {
+    guardianInstruction = resolvedFirstName
+      ? `${resolvedFirstName} will need this code when they answer. Share it with them first.`
+      : "Share this code with them — they'll need it when they answer the call.";
   }
 
   // Voice invites must not expose the token — callers must redeem via the
@@ -276,31 +286,71 @@ export async function createIngressInvite(params: {
   };
 }
 
-export function listIngressInvites(params: {
-  sourceChannel?: string;
-  status?: string;
-}): IngressResult<InviteResponseData[]> {
-  const invites = listInvites({
-    sourceChannel: params.sourceChannel,
-    status: params.status as InviteStatus | undefined,
-  });
-  return {
-    ok: true,
-    data: invites.map((inv) => inviteToResponse(inv)),
-  };
+// ---------------------------------------------------------------------------
+// Mint — gateway-facing projection
+//
+// The gateway owns the canonical invite lifecycle in its own DB, but token
+// generation/hashing and voice fields are assistant-owned. `mintIngressInvite`
+// runs the same `createIngressInvite` path and surfaces the raw token plus the
+// minimal projection the gateway mirrors. The raw token is returned exactly
+// once and never persisted in plaintext.
+// ---------------------------------------------------------------------------
+
+/** Minimal invite projection the gateway mirrors into its own store. */
+export interface GatewayInviteProjection {
+  id: string;
+  /** Hash of whatever code redeems this invite: token hash for token invites,
+   * voice code hash for voice/phone invites. Always non-null and mirrorable. */
+  inviteCodeHash: string;
+  sourceChannel: string;
+  contactId: string;
+  note: string | null;
+  maxUses: number;
+  expiresAt: number;
+}
+
+export interface MintInviteResult {
+  invite: InviteResponseData;
+  rawToken?: string;
+  gateway: GatewayInviteProjection;
 }
 
-export function revokeIngressInvite(
-  inviteId?: string,
-): IngressResult<InviteResponseData> {
-  if (!inviteId) {
-    return { ok: false, error: "inviteId is required for revoke" };
+export async function mintIngressInvite(
+  params: Parameters<typeof createIngressInvite>[0],
+): Promise<IngressResult<MintInviteResult>> {
+  const result = await createIngressInvite(params);
+  if (!result.ok) return result;
+
+  // The persisted row carries fields the response projection omits
+  // (inviteCodeHash); read it back to build the gateway projection.
+  const row = findById(result.data.id);
+  if (!row) {
+    return { ok: false, error: "Invite not found after mint" };
   }
-  const revoked = revokeInvite(inviteId);
-  if (!revoked) {
-    return { ok: false, error: "Invite not found or already revoked" };
+
+  // The gateway mirrors the hash of whatever code redeems this invite. Token
+  // invites carry inviteCodeHash; voice/phone invites gate on voiceCodeHash.
+  const inviteCodeHash = row.inviteCodeHash ?? row.voiceCodeHash;
+  if (!inviteCodeHash) {
+    return { ok: false, error: "Invite is missing a redemption code hash" };
   }
-  return { ok: true, data: inviteToResponse(revoked) };
+
+  return {
+    ok: true,
+    data: {
+      invite: result.data,
+      rawToken: result.data.token,
+      gateway: {
+        id: row.id,
+        inviteCodeHash,
+        sourceChannel: row.sourceChannel,
+        contactId: row.contactId,
+        note: row.note,
+        maxUses: row.maxUses,
+        expiresAt: row.expiresAt,
+      },
+    },
+  };
 }
 
 export async function triggerInviteCall(
@@ -317,35 +367,42 @@ export async function triggerInviteCall(
   }
   if (invite.sourceChannel !== "phone")
     return { ok: false, error: "Only phone invites support call triggering" };
-  if (
-    !invite.expectedExternalUserId ||
-    !invite.friendName ||
-    !invite.guardianName
-  ) {
+  if (!invite.expectedExternalUserId) {
     return { ok: false, error: "Invite is missing required voice metadata" };
   }
+  // Resolve the invitee's name from the bound contact's displayName.
+  // `contact_id` is NOT NULL on the invite row, so every invite is bound;
+  // an empty displayName falls through to the neutral "Hi there" greeting
+  // downstream rather than a stale free-text `friend_name` label.
+  const boundContact = getContact(invite.contactId);
+  const friendName = boundContact?.displayName?.trim() || "";
+  // Guardian label is resolved at runtime by the relay; mirror the legacy
+  // value into the session so STT hints continue to seed correctly.
+  const guardianName = invite.guardianName || resolveGuardianName() || "";
   const result = await startInviteCall({
     phoneNumber: invite.expectedExternalUserId,
-    friendName: invite.friendName,
-    guardianName: invite.guardianName,
+    friendName,
+    guardianName,
   });
   if (!result.ok) return { ok: false, error: result.error };
   return { ok: true, data: { callSid: result.callSid } };
 }
 
-export function redeemIngressInvite(params: {
+export async function redeemIngressInvite(params: {
   token?: string;
   externalUserId?: string;
   externalChatId?: string;
   sourceChannel?: string;
-}): IngressResult<InviteResponseData> {
+}): Promise<
+  IngressResult<{ invite: InviteResponseData; type: RedemptionType }>
+> {
   if (!params.token) {
     return { ok: false, error: "token is required for redeem" };
   }
   if (!params.sourceChannel) {
     return { ok: false, error: "sourceChannel is required for redeem" };
   }
-  const outcome = redeemInviteTyped({
+  const outcome = await redeemInviteTyped({
     rawToken: params.token,
     sourceChannel: params.sourceChannel,
     externalUserId: params.externalUserId,
@@ -354,21 +411,15 @@ export function redeemIngressInvite(params: {
   if (!outcome.ok) {
     return { ok: false, error: outcome.reason };
   }
-  // For already_member, look up the invite by token hash to build the response
-  if (outcome.type === "already_member") {
-    const inv = findByTokenHash(hashToken(params.token));
-    if (!inv) {
-      return { ok: false, error: "Invite not found after redemption" };
-    }
-    return { ok: true, data: inviteToResponse(inv) };
-  }
-  // Look up the invite by token hash — same approach as the already_member path
-  // above. Using findByTokenHash avoids the pagination limit of listInvites.
+  // Look up the invite by token hash for both outcomes (`redeemed` and
+  // `already_member`). Using findByTokenHash avoids the pagination limit of
+  // listInvites. The `type` is surfaced so the gateway can skip mirroring an
+  // `already_member` redemption (which consumes no use).
   const inv = findByTokenHash(hashToken(params.token));
   if (!inv) {
     return { ok: false, error: "Invite not found after redemption" };
   }
-  return { ok: true, data: inviteToResponse(inv) };
+  return { ok: true, data: { invite: inviteToResponse(inv), type: outcome.type } };
 }
 
 export function redeemVoiceInviteCode(params: {
@@ -376,6 +427,6 @@ export function redeemVoiceInviteCode(params: {
   callerExternalUserId: string;
   sourceChannel: "phone";
   code: string;
-}): VoiceRedemptionOutcome {
+}): Promise<VoiceRedemptionOutcome> {
   return redeemVoiceInviteCodeTyped(params);
 }

package/src/runtime/migrations/__tests__/vbundle-builder-fd-leak.test.ts

@@ -119,5 +119,8 @@ describe("streamExportVBundle — descriptor lifecycle", () => {
       // incidental descriptors (temp output file already cleaned up, jitter).
       expect(delta).toBeLessThan(8);
     },
+    // Two full exports of a multi-megabyte workspace (hash pass + tar pass each)
+    // do real disk I/O; the default 5s budget is tight under loaded CI runners.
+    30_000,
   );
 });

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

@@ -133,7 +133,7 @@ const { ROUTES } = await import("../acp-routes.js");
 const { _resetAdapterInstallCacheForTests } =
   await import("../../../acp/auto-install.js");
 
-initializeDb();
+await initializeDb();
 
 afterAll(() => {
   which.restore();

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

@@ -39,7 +39,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "../types.js";
 // DB bootstrap
 // ---------------------------------------------------------------------------
 
-initializeDb();
+await initializeDb();
 
 // ---------------------------------------------------------------------------
 // Helpers