@vellumai/assistant 0.3.28 → 0.4.0

package/src/runtime/guardian-reply-router.ts

@@ -85,6 +85,12 @@ export interface GuardianReplyResult {
   requestId?: string;
   /** Detailed result from the canonical decision primitive (when a decision was attempted). */
   canonicalResult?: CanonicalDecisionResult;
+  /**
+   * When true, the caller should skip legacy approval interception for this
+   * message. Set by the invite handoff bypass so that "open invite flow"
+   * reaches the assistant even when other legacy guardian approvals are pending.
+   */
+  skipApprovalInterception?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -319,7 +325,30 @@ export async function routeGuardianReply(
     }
   }
 
-  // ── 2.5. Deterministic plain-text decisions for known pending targets ──
+  // ── 2.5. Invite handoff bypass for access requests ──
+  // When the guardian sends "open invite flow" and there is at least one
+  // pending access_request, return not_consumed so the message falls through
+  // to the normal assistant turn and can invoke the Trusted Contacts skill.
+  if (messageText.length > 0 && pendingRequests.length > 0) {
+    const normalized = messageText.trim().toLowerCase().replace(/[.!?]+$/g, '');
+    if (normalized === 'open invite flow') {
+      const hasAccessRequest = pendingRequests.some(r => r.kind === 'access_request');
+      if (hasAccessRequest) {
+        log.info(
+          { event: 'router_invite_handoff', pendingCount: pendingRequests.length },
+          'Guardian sent "open invite flow" with pending access_request — passing through to assistant',
+        );
+        return {
+          consumed: false,
+          decisionApplied: false,
+          type: 'not_consumed' as const,
+          skipApprovalInterception: true,
+        };
+      }
+    }
+  }
+
+  // ── 2.6. Deterministic plain-text decisions for known pending targets ──
   // Desktop sessions intentionally do not enable NL classification; when the
   // caller has exactly one known pending request and sends an explicit
   // approve/reject phrase ("approve", "yes", "reject", "no"), apply the
@@ -551,6 +580,7 @@ const EXPLICIT_APPROVE_PHRASES: ReadonlySet<string> = new Set([
   'yes',
   'y',
   'allow',
+  'go for it',
   'go ahead',
   'proceed',
   'do it',

package/src/runtime/ingress-service.ts

@@ -5,6 +5,7 @@
  * both the HTTP routes and the IPC handlers call the same logic.
  */
 
+import { isChannelId } from '../channels/types.js';
 import {
   createInvite,
   type IngressInvite,
@@ -22,11 +23,18 @@ import {
   revokeMember,
   upsertMember,
 } from '../memory/ingress-member-store.js';
+import { isValidE164 } from '../util/phone.js';
+import { generateVoiceCode, hashVoiceCode } from '../util/voice-code.js';
+import { getTransport } from './channel-invite-transport.js';
 import {
   type InviteRedemptionOutcome,
   redeemInvite as redeemInviteTyped,
+  redeemVoiceInviteCode as redeemVoiceInviteCodeTyped,
+  type VoiceRedemptionOutcome,
 } from './invite-redemption-service.js';
 
+import './channel-invite-transports/telegram.js';
+
 // ---------------------------------------------------------------------------
 // Response shapes — used by both HTTP routes and IPC handlers
 // ---------------------------------------------------------------------------
@@ -35,12 +43,20 @@ export interface InviteResponseData {
   id: string;
   sourceChannel: string;
   token?: string;
+  share?: {
+    url: string;
+    displayText: string;
+  };
   tokenHash: string;
   maxUses: number;
   useCount: number;
   expiresAt: number | null;
   status: string;
   note?: string;
+  // Voice invite fields (present only for voice invites)
+  expectedExternalUserId?: string;
+  voiceCode?: string;
+  voiceCodeDigits?: number;
   createdAt: number;
 }
 
@@ -61,17 +77,39 @@ export interface MemberResponseData {
 // Mappers
 // ---------------------------------------------------------------------------
 
-function inviteToResponse(inv: IngressInvite, rawToken?: string): InviteResponseData {
+function buildSharePayload(sourceChannel: string, rawToken?: string): InviteResponseData['share'] | undefined {
+  if (!rawToken || !isChannelId(sourceChannel)) return undefined;
+  const transport = getTransport(sourceChannel);
+  if (!transport?.buildShareableInvite) return undefined;
+
+  try {
+    return transport.buildShareableInvite({
+      rawToken,
+      sourceChannel,
+    });
+  } catch {
+    // Missing channel-specific config (e.g. Telegram bot username) should
+    // not fail invite creation — callers can still use the raw token.
+    return undefined;
+  }
+}
+
+function inviteToResponse(inv: IngressInvite, opts?: { rawToken?: string; voiceCode?: string }): InviteResponseData {
+  const share = buildSharePayload(inv.sourceChannel, opts?.rawToken);
   return {
     id: inv.id,
     sourceChannel: inv.sourceChannel,
-    ...(rawToken ? { token: rawToken } : {}),
+    ...(opts?.rawToken ? { token: opts.rawToken } : {}),
+    ...(share ? { share } : {}),
     tokenHash: inv.tokenHash,
     maxUses: inv.maxUses,
     useCount: inv.useCount,
     expiresAt: inv.expiresAt,
     status: inv.status,
     note: inv.note ?? undefined,
+    ...(inv.expectedExternalUserId ? { expectedExternalUserId: inv.expectedExternalUserId } : {}),
+    ...(opts?.voiceCode ? { voiceCode: opts.voiceCode } : {}),
+    ...(inv.voiceCodeDigits != null ? { voiceCodeDigits: inv.voiceCodeDigits } : {}),
     createdAt: inv.createdAt,
   };
 }
@@ -108,17 +146,46 @@ export function createIngressInvite(params: {
   note?: string;
   maxUses?: number;
   expiresInMs?: number;
+  // Voice invite parameters
+  expectedExternalUserId?: string;
+  voiceCodeDigits?: number;
 }): IngressResult<InviteResponseData> {
   if (!params.sourceChannel) {
     return { ok: false, error: 'sourceChannel is required for create' };
   }
+
+  // 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.
+  let voiceCode: string | undefined;
+  let voiceCodeHash: string | undefined;
+  const isVoice = params.sourceChannel === 'voice';
+
+  if (isVoice) {
+    if (!params.expectedExternalUserId) {
+      return { ok: false, error: 'expectedExternalUserId is required for voice invites' };
+    }
+    if (!isValidE164(params.expectedExternalUserId)) {
+      return { ok: false, error: 'expectedExternalUserId must be in E.164 format (e.g., +15551234567)' };
+    }
+    voiceCode = generateVoiceCode(6);
+    voiceCodeHash = hashVoiceCode(voiceCode);
+  }
+
   const { invite, rawToken } = createInvite({
     sourceChannel: params.sourceChannel,
     note: params.note,
     maxUses: params.maxUses,
     expiresInMs: params.expiresInMs,
+    ...(isVoice ? {
+      expectedExternalUserId: params.expectedExternalUserId,
+      voiceCodeHash,
+      voiceCodeDigits: 6,
+    } : {}),
   });
-  return { ok: true, data: inviteToResponse(invite, rawToken) };
+  // Voice invites must not expose the token — callers must redeem via the
+  // identity-bound voice code flow, not the generic token redemption path.
+  return { ok: true, data: inviteToResponse(invite, { rawToken: isVoice ? undefined : rawToken, voiceCode }) };
 }
 
 export function listIngressInvites(params: {
@@ -172,6 +239,7 @@ export function redeemIngressInvite(params: {
 // ---------------------------------------------------------------------------
 
 export { type InviteRedemptionOutcome } from './invite-redemption-service.js';
+export { type VoiceRedemptionOutcome } from './invite-redemption-service.js';
 
 export function redeemIngressInviteTyped(params: {
   rawToken: string;
@@ -185,6 +253,15 @@ export function redeemIngressInviteTyped(params: {
   return redeemInviteTyped(params);
 }
 
+export function redeemVoiceInviteCode(params: {
+  assistantId?: string;
+  callerExternalUserId: string;
+  sourceChannel: 'voice';
+  code: string;
+}): VoiceRedemptionOutcome {
+  return redeemVoiceInviteCodeTyped(params);
+}
+
 // ---------------------------------------------------------------------------
 // Member operations
 // ---------------------------------------------------------------------------

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

@@ -7,9 +7,12 @@
  * persisted, or returned in the outcome.
  */
 
+import type { ChannelId } from '../channels/types.js';
 import { getSqlite } from '../memory/db.js';
-import { findByTokenHash, hashToken, markInviteExpired, recordInviteUse,redeemInvite as storeRedeemInvite } from '../memory/ingress-invite-store.js';
+import { findActiveVoiceInvites,findByTokenHash, hashToken, markInviteExpired, recordInviteUse, redeemInvite as storeRedeemInvite } from '../memory/ingress-invite-store.js';
 import { findMember, upsertMember } from '../memory/ingress-member-store.js';
+import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
+import { hashVoiceCode } from '../util/voice-code.js';
 
 // ---------------------------------------------------------------------------
 // Outcome type
@@ -20,6 +23,13 @@ export type InviteRedemptionOutcome =
   | { ok: true; type: 'already_member'; memberId: string }
   | { ok: false; reason: 'invalid_token' | 'expired' | 'revoked' | 'max_uses_reached' | 'channel_mismatch' | 'missing_identity' };
 
+// Generic failure reasons for voice redemption — intentionally vague to avoid
+// leaking information about which invites exist or which identity is bound.
+export type VoiceRedemptionOutcome =
+  | { ok: true; type: 'redeemed'; memberId: string; inviteId: string }
+  | { ok: true; type: 'already_member'; memberId: string }
+  | { ok: false; reason: 'invalid_or_expired' };
+
 // ---------------------------------------------------------------------------
 // Error-string to typed-reason mapping
 // ---------------------------------------------------------------------------
@@ -111,6 +121,12 @@ export function redeemInvite(params: {
     // Sentinel error used to trigger a transaction rollback when the invite
     // was concurrently revoked/expired between pre-validation and write time.
     const STALE_INVITE = Symbol('stale_invite');
+    const canonicalMemberId = existingMember.externalUserId ? canonicalizeInboundIdentity(sourceChannel as ChannelId, existingMember.externalUserId) : null;
+    const canonicalCallerId = externalUserId ? canonicalizeInboundIdentity(sourceChannel as ChannelId, externalUserId) : null;
+    const memberMatchesSender = !!(canonicalMemberId && canonicalCallerId && canonicalMemberId === canonicalCallerId);
+    const preservedDisplayName = memberMatchesSender && existingMember.displayName?.trim().length
+      ? existingMember.displayName
+      : displayName;
 
     let reactivated: ReturnType<typeof upsertMember> | undefined;
     try {
@@ -120,7 +136,8 @@ export function redeemInvite(params: {
           sourceChannel,
           externalUserId,
           externalChatId,
-          displayName,
+          // Reactivation should not overwrite a guardian-managed nickname.
+          displayName: preservedDisplayName,
           username,
           status: 'active',
           policy: 'allow',
@@ -179,3 +196,125 @@ export function redeemInvite(params: {
     inviteId: result.invite.id,
   };
 }
+
+// ---------------------------------------------------------------------------
+// redeemVoiceInviteCode
+// ---------------------------------------------------------------------------
+
+/**
+ * Redeem a voice invite code for a caller identified by their E.164 phone number.
+ *
+ * Unlike token-based redemption, voice redemption:
+ *   1. Filters only active voice invites bound to the caller's identity
+ *      (expectedExternalUserId must match callerExternalUserId).
+ *   2. Validates the short numeric code by hashing it and comparing to the
+ *      stored voiceCodeHash.
+ *   3. Enforces expiry and use limits.
+ *   4. On success: upserts/reactivates a member with status 'active', policy 'allow'.
+ *   5. Consumes one invite use atomically (increment useCount).
+ *
+ * Failure responses are intentionally generic ("invalid_or_expired") to prevent
+ * oracle attacks that could reveal which invites exist or which phone numbers
+ * are bound.
+ */
+export function redeemVoiceInviteCode(params: {
+  assistantId?: string;
+  callerExternalUserId: string;
+  sourceChannel: 'voice';
+  code: string;
+}): VoiceRedemptionOutcome {
+  const { assistantId = 'self', callerExternalUserId, code } = params;
+
+  if (!callerExternalUserId) {
+    return { ok: false, reason: 'invalid_or_expired' };
+  }
+
+  // Find all active voice invites bound to the caller's phone number
+  const candidates = findActiveVoiceInvites({
+    assistantId,
+    expectedExternalUserId: callerExternalUserId,
+  });
+
+  if (candidates.length === 0) {
+    return { ok: false, reason: 'invalid_or_expired' };
+  }
+
+  const codeHash = hashVoiceCode(code);
+  const now = Date.now();
+
+  // Search for a matching invite: code hash match, not expired, uses remaining
+  const invite = candidates.find((inv) => {
+    if (inv.voiceCodeHash !== codeHash) return false;
+    if (inv.expiresAt <= now) return false;
+    if (inv.useCount >= inv.maxUses) return false;
+    return true;
+  });
+
+  if (!invite) {
+    // Mark any expired candidates while we're here
+    for (const inv of candidates) {
+      if (inv.expiresAt <= now && inv.status === 'active') {
+        markInviteExpired(inv.id);
+      }
+    }
+    return { ok: false, reason: 'invalid_or_expired' };
+  }
+
+  // Channel enforcement: voice invites can only be redeemed on the voice channel
+  if (invite.sourceChannel !== 'voice') {
+    return { ok: false, reason: 'invalid_or_expired' };
+  }
+
+  // Check for existing membership
+  const existingMember = findMember({
+    assistantId: invite.assistantId,
+    sourceChannel: 'voice',
+    externalUserId: callerExternalUserId,
+  });
+
+  if (existingMember && existingMember.status === 'active') {
+    return { ok: true, type: 'already_member', memberId: existingMember.id };
+  }
+
+  // Blocked members cannot bypass the guardian's explicit block
+  if (existingMember && existingMember.status === 'blocked') {
+    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;
+
+  try {
+    getSqlite().transaction(() => {
+      const member = upsertMember({
+        assistantId: invite.assistantId,
+        sourceChannel: 'voice',
+        externalUserId: callerExternalUserId,
+        status: 'active',
+        policy: 'allow',
+        inviteId: invite.id,
+      });
+      memberId = member.id;
+
+      const recorded = recordInviteUse({
+        inviteId: invite.id,
+        externalUserId: callerExternalUserId,
+      });
+
+      if (!recorded) throw STALE_INVITE;
+    }).immediate();
+  } catch (err) {
+    if (err === STALE_INVITE) {
+      return { ok: false, reason: 'invalid_or_expired' };
+    }
+    throw err;
+  }
+
+  return {
+    ok: true,
+    type: 'redeemed',
+    memberId: memberId!,
+    inviteId: invite.id,
+  };
+}

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

@@ -11,7 +11,7 @@ import type {
   ApprovalUIMetadata,
 } from '../channel-approval-types.js';
 import type { DenialReason } from '../guardian-context-resolver.js';
-export type { ActorRole, DenialReason, GuardianContext } from '../guardian-context-resolver.js';
+export type { ActorTrustClass, DenialReason, GuardianContext } from '../guardian-context-resolver.js';
 export { toGuardianRuntimeContext } from '../guardian-context-resolver.js';
 
 /** Canonicalize assistantId for channel ingress paths. */

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

@@ -23,7 +23,7 @@ export {
 } from './channel-inbound-routes.js';
 export {
   _setTestPollMaxWait,
-  type ActorRole,
+  type ActorTrustClass,
   type DenialReason,
   GATEWAY_ORIGIN_HEADER,
   type GuardianContext,

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

@@ -283,7 +283,7 @@ export async function handleSendMessage(
     const session = await smDeps.getOrCreateSession(mapping.conversationId);
     // HTTP API is a trusted local ingress (same as IPC) — set guardian context
     // so that memory extraction is not silently disabled by unverified provenance.
-    session.setGuardianContext({ actorRole: 'guardian', sourceChannel: sourceChannel ?? 'http' });
+    session.setGuardianContext({ trustClass: 'guardian', sourceChannel: sourceChannel ?? 'http' });
     const onEvent = makeHubPublisher(smDeps, mapping.conversationId, session);
 
     const attachments = hasAttachments
@@ -353,7 +353,7 @@ export async function handleSendMessage(
       mapping.conversationId,
       content ?? '',
       hasAttachments ? attachmentIds : undefined,
-      { guardianContext: { actorRole: 'guardian', sourceChannel } },
+      { guardianContext: { trustClass: 'guardian', sourceChannel } },
       sourceChannel,
       sourceInterface,
     );

package/src/runtime/routes/guardian-approval-interception.ts

@@ -100,7 +100,7 @@ export async function handleApprovalInterception(
   // request targeting this chat, the message might be a decision on behalf
   // of a non-guardian requester.
   if (
-    guardianCtx.actorRole === 'guardian' &&
+    guardianCtx.trustClass === 'guardian' &&
     senderExternalUserId
   ) {
     // Callback/button path: deterministic and takes priority.
@@ -161,7 +161,7 @@ export async function handleApprovalInterception(
     if (guardianApproval) {
       // Validate that the sender is the specific guardian who was assigned
       // this approval request. This is a defense-in-depth check — the
-      // actorRole check above already verifies the sender is a guardian,
+      // trustClass check above already verifies the sender is a guardian,
       // but this catches edge cases like binding rotation between request
       // creation and decision.
       if (senderExternalUserId !== guardianApproval.guardianExternalUserId) {
@@ -548,9 +548,15 @@ export async function handleApprovalInterception(
   const pendingPrompt = getChannelApprovalPrompt(conversationId);
   if (!pendingPrompt) return { handled: false };
 
-  // When the sender is from an unverified channel, auto-deny any pending
-  // confirmation and block self-approval.
-  if (guardianCtx.actorRole === 'unverified_channel') {
+  // Legacy unverified-channel equivalent:
+  // unknown trust + explicit denial reason (`no_identity` / `no_binding`).
+  // Unknown without a denial reason means identity-known, non-member sender
+  // in a shared channel; that case must not force-reject someone else's request.
+  const isLegacyUnverifiedSender = guardianCtx.trustClass === 'unknown' && !!guardianCtx.denialReason;
+
+  // When the sender is from a legacy-unverified channel actor, auto-deny any
+  // pending confirmation and block self-approval.
+  if (isLegacyUnverifiedSender) {
     const pending = getApprovalInfoByConversation(conversationId);
     if (pending.length > 0) {
       handleChannelDecision(
@@ -569,7 +575,12 @@ export async function handleApprovalInterception(
   // When the sender is a non-guardian and there's a pending guardian approval
   // for this conversation's request, block self-approval. The non-guardian must
   // wait for the guardian to decide.
-  if (guardianCtx.actorRole === 'non-guardian') {
+  //
+  // Include identity-known, non-member senders (`unknown` without denialReason)
+  // so shared-channel participants can't approve/deny someone else's pending request.
+  const isIdentityKnownNonGuardian = guardianCtx.trustClass === 'trusted_contact'
+    || (guardianCtx.trustClass === 'unknown' && !guardianCtx.denialReason);
+  if (isIdentityKnownNonGuardian) {
     const pending = getApprovalInfoByConversation(conversationId);
     if (pending.length > 0) {
       const guardianApprovalForRequest = getPendingApprovalForRequest(pending[0].requestId);

package/src/runtime/routes/inbound-message-handler.ts

@@ -76,6 +76,7 @@ import { handleApprovalInterception } from './guardian-approval-interception.js'
 import { deliverGeneratedApprovalPrompt } from './guardian-approval-prompt.js';
 
 import '../channel-invite-transports/telegram.js';
+import '../channel-invite-transports/voice.js';
 
 const log = getLogger('runtime-http');
 
@@ -229,7 +230,7 @@ export async function handleChannelInbound(
     typeof (rawCommandIntentForAcl as Record<string, unknown>).payload === 'string' &&
     ((rawCommandIntentForAcl as Record<string, unknown>).payload as string).startsWith('gv_');
 
-  // Parse invite token from /start iv_<token> commands using the transport
+  // Parse invite token from /start payloads using the channel transport
   // adapter. The token is extracted once here so both the ACL bypass and
   // the intercept handler can reference it without re-parsing.
   const commandIntentForAcl = rawCommandIntentForAcl && typeof rawCommandIntentForAcl === 'object' && !Array.isArray(rawCommandIntentForAcl)
@@ -291,7 +292,7 @@ export async function handleChannelInbound(
       }
 
       // ── Invite token intercept (non-member) ──
-      // /start iv_<token> deep links grant access without guardian approval.
+      // /start invite deep links grant access without guardian approval.
       // Intercept here — before the deny gate — so valid invites short-circuit
       // the ACL rejection and never reach the agent pipeline.
       if (inviteToken && denyNonMember) {
@@ -774,6 +775,21 @@ export async function handleChannelInbound(
     const guardianVerifyOutcome: 'verified' | 'failed' = verifyResult.success ? 'verified' : 'failed';
 
     if (verifyResult.success) {
+      const existingMember = (canonicalSenderId ?? rawSenderId)
+        ? findMember({
+          assistantId: canonicalAssistantId,
+          sourceChannel,
+          externalUserId: canonicalSenderId ?? rawSenderId!,
+          externalChatId,
+        })
+        : null;
+      const memberMatchesSender = existingMember?.externalUserId
+        ? canonicalizeInboundIdentity(sourceChannel, existingMember.externalUserId) === (canonicalSenderId ?? rawSenderId)
+        : false;
+      const preservedDisplayName = memberMatchesSender && existingMember?.displayName?.trim().length
+        ? existingMember.displayName
+        : body.senderName;
+
       upsertMember({
         assistantId: canonicalAssistantId,
         sourceChannel,
@@ -781,7 +797,8 @@ export async function handleChannelInbound(
         externalChatId,
         status: 'active',
         policy: 'allow',
-        displayName: body.senderName,
+        // Keep guardian-curated member name stable across re-verification.
+        displayName: preservedDisplayName,
         username: body.senderUsername,
       });
 
@@ -898,8 +915,14 @@ export async function handleChannelInbound(
     externalChatId,
     senderExternalUserId: rawSenderId,
     senderUsername: body.senderUsername,
+    senderDisplayName: body.senderName,
   });
 
+  // Hoisted flag: set by the canonical guardian reply router when the invite
+  // handoff bypass fires. Prevents legacy approval interception from swallowing
+  // the message when other approvals are pending in the same chat.
+  let skipApprovalInterception = false;
+
   // ── Canonical guardian reply router ──
   // Attempts to route inbound messages through the canonical decision pipeline
   // before falling through to the legacy approval interception. Handles
@@ -910,7 +933,7 @@ export async function handleChannelInbound(
     replyCallbackUrl &&
     (trimmedContent.length > 0 || hasCallbackData) &&
     rawSenderId &&
-    guardianCtx.actorRole === 'guardian'
+    guardianCtx.trustClass === 'guardian'
   ) {
     // Compute destination-scoped pending request hints so the router can
     // discover canonical requests delivered to this chat even when the
@@ -983,13 +1006,21 @@ export async function handleChannelInbound(
         requestId: routerResult.requestId,
       });
     }
+
+    if (routerResult.skipApprovalInterception) {
+      skipApprovalInterception = true;
+    }
   }
 
   // ── Approval interception ──
   // Keep this active whenever callback context is available.
+  // Skipped when the canonical router flagged skipApprovalInterception (e.g.
+  // invite handoff bypass) to prevent the legacy interceptor from swallowing
+  // messages that should reach the assistant.
   if (
     replyCallbackUrl &&
-    !result.duplicate
+    !result.duplicate &&
+    !skipApprovalInterception
   ) {
     const approvalResult = await handleApprovalInterception({
       conversationId: result.conversationId,
@@ -1369,7 +1400,7 @@ function startPendingApprovalPromptWatcher(params: {
   conversationId: string;
   sourceChannel: ChannelId;
   externalChatId: string;
-  guardianActorRole: GuardianContext['actorRole'];
+  guardianTrustClass: GuardianContext['trustClass'];
   replyCallbackUrl: string;
   bearerToken?: string;
   assistantId?: string;
@@ -1379,7 +1410,7 @@ function startPendingApprovalPromptWatcher(params: {
     conversationId,
     sourceChannel,
     externalChatId,
-    guardianActorRole,
+    guardianTrustClass,
     replyCallbackUrl,
     bearerToken,
     assistantId,
@@ -1388,7 +1419,7 @@ function startPendingApprovalPromptWatcher(params: {
 
   // Approval prompt delivery is guardian-only. Non-guardian and unverified
   // actors must never receive approval prompt broadcasts for the conversation.
-  if (guardianActorRole !== 'guardian') {
+  if (guardianTrustClass !== 'guardian') {
     return () => {};
   }
 
@@ -1470,7 +1501,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
         conversationId,
         sourceChannel,
         externalChatId,
-        guardianActorRole: guardianCtx.actorRole,
+        guardianTrustClass: guardianCtx.trustClass,
         replyCallbackUrl,
         bearerToken,
         assistantId,
@@ -1494,7 +1525,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
           },
           assistantId,
           guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
-          isInteractive: guardianCtx.actorRole === 'guardian',
+          isInteractive: guardianCtx.trustClass === 'guardian',
           ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
         },
         sourceChannel,