@vellumai/assistant 0.4.32 → 0.4.34

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

@@ -13,6 +13,7 @@ import { upsertMember } from "../contacts/contacts-write.js";
 import { getSqlite } from "../memory/db.js";
 import {
   findActiveVoiceInvites,
+  findByInviteCodeHash,
   findByTokenHash,
   hashToken,
   markInviteExpired,
@@ -20,7 +21,6 @@ import {
 } from "../memory/invite-store.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { hashVoiceCode } from "../util/voice-code.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
 
 // ---------------------------------------------------------------------------
 // Outcome type
@@ -83,7 +83,6 @@ export function redeemInvite(params: {
     externalChatId,
     displayName,
     username,
-    assistantId,
   } = params;
 
   if (!externalUserId && !externalChatId) {
@@ -179,7 +178,6 @@ export function redeemInvite(params: {
       getSqlite()
         .transaction(() => {
           reactivated = upsertMember({
-            assistantId: assistantId ?? invite.assistantId,
             sourceChannel,
             externalUserId,
             externalChatId,
@@ -226,7 +224,6 @@ export function redeemInvite(params: {
     getSqlite()
       .transaction(() => {
         freshResult = upsertMember({
-          assistantId: assistantId ?? invite.assistantId,
           sourceChannel,
           externalUserId,
           externalChatId,
@@ -287,11 +284,7 @@ export function redeemVoiceInviteCode(params: {
   sourceChannel: "voice";
   code: string;
 }): VoiceRedemptionOutcome {
-  const {
-    assistantId = DAEMON_INTERNAL_ASSISTANT_ID,
-    callerExternalUserId,
-    code,
-  } = params;
+  const { callerExternalUserId, code } = params;
 
   if (!callerExternalUserId) {
     return { ok: false, reason: "invalid_or_expired" };
@@ -299,7 +292,6 @@ export function redeemVoiceInviteCode(params: {
 
   // Find all active voice invites bound to the caller's phone number
   const candidates = findActiveVoiceInvites({
-    assistantId,
     expectedExternalUserId: callerExternalUserId,
   });
 
@@ -371,7 +363,6 @@ export function redeemVoiceInviteCode(params: {
     getSqlite()
       .transaction(() => {
         const writeResult = upsertMember({
-          assistantId: invite.assistantId,
           sourceChannel: "voice",
           externalUserId: callerExternalUserId,
           externalChatId: callerExternalUserId,
@@ -404,3 +395,192 @@ export function redeemVoiceInviteCode(params: {
     inviteId: invite.id,
   };
 }
+
+// ---------------------------------------------------------------------------
+// redeemInviteByCode
+// ---------------------------------------------------------------------------
+
+/**
+ * Redeem an invite using a 6-digit invite code (channel-agnostic).
+ *
+ * Unlike token-based redemption which uses deep links, code redemption works
+ * by intercepting bare 6-digit messages on channels with codeRedemptionEnabled.
+ * The code is hashed and looked up via `findByInviteCodeHash`.
+ *
+ * Validation: active status, not expired, uses remaining, channel match.
+ * On success: upserts/reactivates a member with status 'active', policy 'allow'.
+ */
+export function redeemInviteByCode(params: {
+  code: string;
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  assistantId?: string;
+}): InviteRedemptionOutcome {
+  const {
+    code,
+    sourceChannel,
+    externalUserId,
+    externalChatId,
+    displayName,
+    username,
+  } = params;
+
+  if (!externalUserId && !externalChatId) {
+    return { ok: false, reason: "missing_identity" };
+  }
+
+  const codeHash = hashVoiceCode(code);
+  const invite = findByInviteCodeHash(codeHash, sourceChannel);
+
+  if (!invite) {
+    return { ok: false, reason: "invalid_token" };
+  }
+
+  if (invite.status !== "active") {
+    const mapped = STORE_ERROR_TO_REASON[`invite_${invite.status}`];
+    if (mapped) return mapped;
+    return { ok: false, reason: "invalid_token" };
+  }
+
+  if (invite.expiresAt <= Date.now()) {
+    markInviteExpired(invite.id);
+    return { ok: false, reason: "expired" };
+  }
+
+  if (invite.useCount >= invite.maxUses) {
+    return { ok: false, reason: "max_uses_reached" };
+  }
+
+  // Code is valid — now safe to check existing membership without leaking
+  // membership status to callers with bogus codes.
+  const canonicalUserId = externalUserId
+    ? (canonicalizeInboundIdentity(
+        sourceChannel as ChannelId,
+        externalUserId,
+      ) ?? externalUserId)
+    : undefined;
+  const contactResult = findContactChannel({
+    channelType: sourceChannel,
+    externalUserId: canonicalUserId,
+    externalChatId: externalChatId,
+  });
+  const existingChannel = contactResult?.channel ?? null;
+  const existingContact = contactResult?.contact ?? null;
+
+  if (existingChannel && existingChannel.status === "active") {
+    return { ok: true, type: "already_member", memberId: existingChannel.id };
+  }
+
+  // Blocked members cannot bypass the guardian's explicit block via invite
+  // codes. Return the same generic failure as an invalid token to avoid
+  // leaking membership status to the caller.
+  if (existingChannel && existingChannel.status === "blocked") {
+    return { ok: false, reason: "invalid_token" };
+  }
+
+  // Inactive member reactivation: reactivate via upsertMember and consume
+  // an invite use atomically.
+  if (existingChannel) {
+    const STALE_INVITE_REACTIVATE = Symbol("stale_invite_reactivate");
+    const canonicalMemberId = existingChannel.externalUserId
+      ? canonicalizeInboundIdentity(
+          sourceChannel as ChannelId,
+          existingChannel.externalUserId,
+        )
+      : null;
+    const canonicalCallerId = externalUserId
+      ? canonicalizeInboundIdentity(sourceChannel as ChannelId, externalUserId)
+      : null;
+    const memberMatchesSender = !!(
+      canonicalMemberId &&
+      canonicalCallerId &&
+      canonicalMemberId === canonicalCallerId
+    );
+    const preservedDisplayName =
+      memberMatchesSender && existingContact?.displayName?.trim().length
+        ? existingContact.displayName
+        : displayName;
+
+    let reactivated: ReturnType<typeof upsertMember> | undefined;
+    try {
+      getSqlite()
+        .transaction(() => {
+          reactivated = upsertMember({
+            sourceChannel,
+            externalUserId,
+            externalChatId,
+            displayName: preservedDisplayName,
+            username,
+            status: "active",
+            policy: "allow",
+            inviteId: invite.id,
+          });
+
+          const recorded = recordInviteUse({
+            inviteId: invite.id,
+            externalUserId,
+            externalChatId,
+          });
+
+          if (!recorded) throw STALE_INVITE_REACTIVATE;
+        })
+        .immediate();
+    } catch (err) {
+      if (err === STALE_INVITE_REACTIVATE) {
+        return { ok: false, reason: "invalid_token" };
+      }
+      throw err;
+    }
+
+    return {
+      ok: true,
+      type: "redeemed",
+      memberId: reactivated!.channel.id,
+      inviteId: invite.id,
+    };
+  }
+
+  // Fresh member creation: upsert into contacts tables and consume an invite
+  // use atomically.
+  const STALE_INVITE_FRESH = Symbol("stale_invite_fresh");
+  let freshResult: ReturnType<typeof upsertMember> | undefined;
+  try {
+    getSqlite()
+      .transaction(() => {
+        freshResult = upsertMember({
+          sourceChannel,
+          externalUserId,
+          externalChatId,
+          displayName,
+          username,
+          status: "active",
+          policy: "allow",
+          inviteId: invite.id,
+        });
+
+        const recorded = recordInviteUse({
+          inviteId: invite.id,
+          externalUserId,
+          externalChatId,
+        });
+
+        if (!recorded) throw STALE_INVITE_FRESH;
+      })
+      .immediate();
+  } catch (err) {
+    if (err === STALE_INVITE_FRESH) {
+      return { ok: false, reason: "invalid_token" };
+    }
+    throw err;
+  }
+
+  return {
+    ok: true,
+    type: "redeemed",
+    memberId: freshResult!.channel.id,
+    inviteId: invite.id,
+  };
+}

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

@@ -13,13 +13,13 @@ import type { InviteRedemptionOutcome } from "./invite-redemption-service.js";
 // ---------------------------------------------------------------------------
 
 export const INVITE_REPLY_TEMPLATES = {
-  redeemed: "Welcome! You've been granted access via invite link.",
+  redeemed: "Welcome! You've been granted access.",
   already_member: "You already have access.",
-  invalid_token: "This invite link is no longer valid.",
-  expired: "This invite link is no longer valid.",
-  revoked: "This invite link is no longer valid.",
-  max_uses_reached: "This invite link is no longer valid.",
-  channel_mismatch: "This invite link is not valid for this channel.",
+  invalid_token: "This invite is no longer valid.",
+  expired: "This invite is no longer valid.",
+  revoked: "This invite is no longer valid.",
+  max_uses_reached: "This invite is no longer valid.",
+  channel_mismatch: "This invite is not valid for this channel.",
   missing_identity:
     "Unable to process this invite. Please contact the person who shared it.",
   generic_failure:

package/src/runtime/invite-service.ts

@@ -9,6 +9,11 @@
  */
 
 import { isChannelId } from "../channels/types.js";
+import {
+  DECLINED_BY_USER_SENTINEL,
+  DEFAULT_USER_REFERENCE,
+  resolveGuardianName,
+} from "../config/user-reference.js";
 import {
   createInvite,
   findByTokenHash,
@@ -20,7 +25,7 @@ import {
 } from "../memory/invite-store.js";
 import { isValidE164 } from "../util/phone.js";
 import { generateVoiceCode, hashVoiceCode } from "../util/voice-code.js";
-import { getTransport } from "./channel-invite-transport.js";
+import { getInviteAdapterRegistry } from "./channel-invite-transport.js";
 import {
   type InviteRedemptionOutcome,
   redeemInvite as redeemInviteTyped,
@@ -28,8 +33,6 @@ import {
   type VoiceRedemptionOutcome,
 } from "./invite-redemption-service.js";
 
-import "./channel-invite-transports/telegram.js";
-
 // ---------------------------------------------------------------------------
 // Response shapes — used by both HTTP routes and IPC handlers
 // ---------------------------------------------------------------------------
@@ -54,6 +57,10 @@ export interface InviteResponseData {
   voiceCodeDigits?: number;
   friendName?: string;
   guardianName?: string;
+  // Non-voice invite fields (present only for non-voice invites)
+  inviteCode?: string;
+  guardianInstruction?: string;
+  channelHandle?: string;
   createdAt: number;
 }
 
@@ -66,11 +73,11 @@ function buildSharePayload(
   rawToken?: string,
 ): InviteResponseData["share"] | undefined {
   if (!rawToken || !isChannelId(sourceChannel)) return undefined;
-  const transport = getTransport(sourceChannel);
-  if (!transport?.buildShareableInvite) return undefined;
+  const adapter = getInviteAdapterRegistry().get(sourceChannel);
+  if (!adapter?.buildShareLink) return undefined;
 
   try {
-    return transport.buildShareableInvite({
+    return adapter.buildShareLink({
       rawToken,
       sourceChannel,
     });
@@ -83,7 +90,13 @@ function buildSharePayload(
 
 function inviteToResponse(
   inv: IngressInvite,
-  opts?: { rawToken?: string; voiceCode?: string },
+  opts?: {
+    rawToken?: string;
+    voiceCode?: string;
+    inviteCode?: string;
+    guardianInstruction?: string;
+    channelHandle?: string;
+  },
 ): InviteResponseData {
   const share = buildSharePayload(inv.sourceChannel, opts?.rawToken);
   return {
@@ -106,6 +119,11 @@ function inviteToResponse(
       : {}),
     ...(inv.friendName ? { friendName: inv.friendName } : {}),
     ...(inv.guardianName ? { guardianName: inv.guardianName } : {}),
+    ...(opts?.inviteCode ? { inviteCode: opts.inviteCode } : {}),
+    ...(opts?.guardianInstruction
+      ? { guardianInstruction: opts.guardianInstruction }
+      : {}),
+    ...(opts?.channelHandle ? { channelHandle: opts.channelHandle } : {}),
     createdAt: inv.createdAt,
   };
 }
@@ -127,6 +145,8 @@ export function createIngressInvite(params: {
   note?: string;
   maxUses?: number;
   expiresInMs?: number;
+  // Contact display name for personalizing guardian instructions
+  contactName?: string;
   // Voice invite parameters
   expectedExternalUserId?: string;
   voiceCodeDigits?: number;
@@ -142,8 +162,15 @@ export function createIngressInvite(params: {
   // exactly once and never stored.
   let voiceCode: string | undefined;
   let voiceCodeHash: string | undefined;
+  let effectiveGuardianName: string | undefined;
   const isVoice = params.sourceChannel === "voice";
 
+  // For non-voice invites: generate a 6-digit invite code for guardian-mediated
+  // redemption. The plaintext code is returned once in the response; only the
+  // hash is persisted for later redemption lookup.
+  let inviteCode: string | undefined;
+  let inviteCodeHash: string | undefined;
+
   if (isVoice) {
     if (!params.expectedExternalUserId) {
       return {
@@ -161,14 +188,20 @@ export function createIngressInvite(params: {
     if (typeof params.friendName !== "string" || !params.friendName.trim()) {
       return { ok: false, error: "friendName is required for voice invites" };
     }
+    effectiveGuardianName =
+      params.guardianName?.trim() || resolveGuardianName();
     if (
-      typeof params.guardianName !== "string" ||
-      !params.guardianName.trim()
+      !effectiveGuardianName ||
+      effectiveGuardianName === DEFAULT_USER_REFERENCE ||
+      effectiveGuardianName === DECLINED_BY_USER_SENTINEL
     ) {
       return { ok: false, error: "guardianName is required for voice invites" };
     }
     voiceCode = generateVoiceCode(6);
     voiceCodeHash = hashVoiceCode(voiceCode);
+  } else {
+    inviteCode = generateVoiceCode(6);
+    inviteCodeHash = hashVoiceCode(inviteCode);
   }
 
   const { invite, rawToken } = createInvite({
@@ -182,10 +215,44 @@ export function createIngressInvite(params: {
           voiceCodeHash,
           voiceCodeDigits: 6,
           friendName: params.friendName,
-          guardianName: params.guardianName,
+          guardianName: effectiveGuardianName,
         }
-      : {}),
+      : { inviteCodeHash }),
   });
+
+  // Build guardian instruction for non-voice invites
+  let guardianInstruction: string | undefined;
+  let channelHandle: string | undefined;
+  if (!isVoice && inviteCode) {
+    const channelId = isChannelId(params.sourceChannel)
+      ? params.sourceChannel
+      : undefined;
+    const adapter = channelId
+      ? getInviteAdapterRegistry().get(channelId)
+      : undefined;
+
+    if (adapter?.buildGuardianInstruction) {
+      try {
+        const adapterResult = adapter.buildGuardianInstruction({
+          inviteCode,
+          contactName: params.contactName,
+        });
+        if (adapterResult) {
+          guardianInstruction = adapterResult.instruction;
+          channelHandle = adapterResult.channelHandle;
+        }
+      } catch {
+        // Fall through to generic instruction if adapter fails
+      }
+    }
+
+    if (!guardianInstruction) {
+      const contactLabel = params.contactName || "the contact";
+      const channelLabel = params.sourceChannel;
+      guardianInstruction = `Tell ${contactLabel} to contact the assistant on ${channelLabel} and provide the code ${inviteCode}.`;
+    }
+  }
+
   // Voice invites must not expose the token — callers must redeem via the
   // identity-bound voice code flow, not the generic token redemption path.
   return {
@@ -193,6 +260,9 @@ export function createIngressInvite(params: {
     data: inviteToResponse(invite, {
       rawToken: isVoice ? undefined : rawToken,
       voiceCode,
+      inviteCode,
+      guardianInstruction,
+      channelHandle,
     }),
   };
 }

package/src/runtime/local-actor-identity.ts

@@ -41,7 +41,7 @@ export function resolveLocalIpcTrustContext(
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
   // Try contacts-first for the vellum guardian channel
-  const guardianResult = findGuardianForChannel("vellum", assistantId);
+  const guardianResult = findGuardianForChannel("vellum");
   if (guardianResult && guardianResult.contact.principalId) {
     const guardianPrincipalId = guardianResult.contact.principalId;
     const trustCtx = resolveTrustContext({
@@ -93,10 +93,7 @@ export function resolveLocalIpcAuthContext(sessionId: string): AuthContext {
   const authContext = buildIpcAuthContext(sessionId);
 
   // Enrich with the guardian principal ID from contacts-first path
-  const guardianResult = findGuardianForChannel(
-    "vellum",
-    authContext.assistantId,
-  );
+  const guardianResult = findGuardianForChannel("vellum");
   if (guardianResult && guardianResult.contact.principalId) {
     return {
       ...authContext,

package/src/runtime/routes/access-request-decision.ts

@@ -86,7 +86,6 @@ export function handleAccessRequestDecision(
   // so only the original requester can consume the code. Mark as
   // trusted_contact so the consume path skips guardian binding creation.
   const session = createOutboundSession({
-    assistantId: approval.assistantId,
     channel: approval.channel,
     expectedExternalUserId: approval.requesterExternalUserId,
     expectedChatId: approval.requesterChatId,
@@ -141,6 +140,40 @@ export async function deliverVerificationCodeToGuardian(params: {
   }
 }
 
+/**
+ * Resolve the delivery target for requester notifications. On Slack,
+ * posting to a user ID (rather than the originating channel) delivers
+ * the message as a DM, which is less disruptive than replying in a
+ * shared channel. When routing to a DM, the `threadTs` query param is
+ * stripped from the callback URL because it belongs to the guardian's
+ * channel thread and would cause `thread_not_found` errors in the DM.
+ */
+function resolveRequesterTarget(params: {
+  channel?: string;
+  replyCallbackUrl: string;
+  requesterChatId: string;
+  requesterExternalUserId?: string;
+}): { chatId: string; callbackUrl: string } {
+  if (params.channel === "slack" && params.requesterExternalUserId) {
+    let callbackUrl = params.replyCallbackUrl;
+    try {
+      const url = new URL(params.replyCallbackUrl);
+      url.searchParams.delete("threadTs");
+      callbackUrl = url.toString();
+    } catch {
+      // Malformed URL — use as-is; the downstream fetch will handle the error.
+    }
+    return {
+      chatId: params.requesterExternalUserId,
+      callbackUrl,
+    };
+  }
+  return {
+    chatId: params.requesterChatId,
+    callbackUrl: params.replyCallbackUrl,
+  };
+}
+
 /**
  * Notify the requester that the guardian has approved their access request
  * and they should enter the verification code they receive from the guardian.
@@ -150,16 +183,20 @@ export async function notifyRequesterOfApproval(params: {
   requesterChatId: string;
   assistantId: string;
   bearerToken?: string;
+  channel?: string;
+  requesterExternalUserId?: string;
 }): Promise<void> {
   const text =
     "Your access request has been approved! " +
     "Please enter the 6-digit verification code you receive from the guardian.";
 
+  const target = resolveRequesterTarget(params);
+
   try {
     await deliverChannelReply(
-      params.replyCallbackUrl,
+      target.callbackUrl,
       {
-        chatId: params.requesterChatId,
+        chatId: target.chatId,
         text,
         assistantId: params.assistantId,
       },
@@ -183,16 +220,20 @@ export async function notifyRequesterOfDeliveryFailure(params: {
   requesterChatId: string;
   assistantId: string;
   bearerToken?: string;
+  channel?: string;
+  requesterExternalUserId?: string;
 }): Promise<void> {
   const text =
     "Your access request was approved, but we were unable to " +
     "deliver the verification code. Please try again later.";
 
+  const target = resolveRequesterTarget(params);
+
   try {
     await deliverChannelReply(
-      params.replyCallbackUrl,
+      target.callbackUrl,
       {
-        chatId: params.requesterChatId,
+        chatId: target.chatId,
         text,
         assistantId: params.assistantId,
       },
@@ -214,14 +255,18 @@ export async function notifyRequesterOfDenial(params: {
   requesterChatId: string;
   assistantId: string;
   bearerToken?: string;
+  channel?: string;
+  requesterExternalUserId?: string;
 }): Promise<void> {
   const text = "Your access request has been denied by the guardian.";
 
+  const target = resolveRequesterTarget(params);
+
   try {
     await deliverChannelReply(
-      params.replyCallbackUrl,
+      target.callbackUrl,
       {
-        chatId: params.requesterChatId,
+        chatId: target.chatId,
         text,
         assistantId: params.assistantId,
       },

package/src/runtime/routes/approval-strategies/guardian-callback-strategy.ts

@@ -99,7 +99,6 @@ export async function handleGuardianCallbackDecision(
         callbackDecision.requestId,
         sourceChannel,
         conversationExternalId,
-        assistantId,
       )
     : null;
 
@@ -110,7 +109,6 @@ export async function handleGuardianCallbackDecision(
     const allPending = getAllPendingApprovalsByGuardianChat(
       sourceChannel,
       conversationExternalId,
-      assistantId,
     );
     if (allPending.length === 1) {
       guardianApproval = allPending[0];
@@ -141,7 +139,6 @@ export async function handleGuardianCallbackDecision(
     const allPending = getAllPendingApprovalsByGuardianChat(
       sourceChannel,
       conversationExternalId,
-      assistantId,
     );
     if (allPending.length === 1) {
       guardianApproval = allPending[0];
@@ -204,7 +201,6 @@ export async function handleGuardianCallbackDecision(
   const allGuardianPending = getAllPendingApprovalsByGuardianChat(
     sourceChannel,
     conversationExternalId,
-    assistantId,
   );
   // Only present approvals that belong to this sender so the engine
   // does not offer disambiguation for requests assigned to a rotated
@@ -609,7 +605,6 @@ async function handleLegacyDecision(params: {
         legacyGuardianDecision.requestId,
         sourceChannel,
         conversationExternalId,
-        assistantId,
       );
       if (!resolvedByRequest) {
         // The referenced request doesn't match any pending guardian
@@ -789,6 +784,8 @@ async function handleAccessRequestApproval(
       requesterChatId: approval.requesterChatId,
       assistantId,
       bearerToken,
+      channel: approval.channel,
+      requesterExternalUserId: approval.requesterExternalUserId,
     });
 
     // Emit both guardian_decision and denied signals so all lifecycle
@@ -805,7 +802,6 @@ async function handleAccessRequestApproval(
       sourceEventName: "ingress.trusted_contact.guardian_decision",
       sourceChannel: approval.channel,
       sourceSessionId: approval.conversationId,
-      assistantId,
       attentionHints: {
         requiresAction: false,
         urgency: "medium",
@@ -820,7 +816,6 @@ async function handleAccessRequestApproval(
       sourceEventName: "ingress.trusted_contact.denied",
       sourceChannel: approval.channel,
       sourceSessionId: approval.conversationId,
-      assistantId,
       attentionHints: {
         requiresAction: false,
         urgency: "low",
@@ -863,6 +858,8 @@ async function handleAccessRequestApproval(
       requesterChatId: approval.requesterChatId,
       assistantId,
       bearerToken,
+      channel: approval.channel,
+      requesterExternalUserId: approval.requesterExternalUserId,
     });
   } else {
     // Let the requester know something went wrong without revealing details
@@ -871,6 +868,8 @@ async function handleAccessRequestApproval(
       requesterChatId: approval.requesterChatId,
       assistantId,
       bearerToken,
+      channel: approval.channel,
+      requesterExternalUserId: approval.requesterExternalUserId,
     });
   }
 
@@ -885,7 +884,6 @@ async function handleAccessRequestApproval(
       sourceEventName: "ingress.trusted_contact.guardian_decision",
       sourceChannel: approval.channel,
       sourceSessionId: approval.conversationId,
-      assistantId,
       attentionHints: {
         requiresAction: false,
         urgency: "medium",
@@ -912,7 +910,6 @@ async function handleAccessRequestApproval(
       sourceEventName: "ingress.trusted_contact.verification_sent",
       sourceChannel: approval.channel,
       sourceSessionId: approval.conversationId,
-      assistantId,
       attentionHints: {
         requiresAction: false,
         urgency: "low",