@vellumai/assistant 0.3.27 → 0.4.0

package/src/runtime/http-server.ts

@@ -93,6 +93,10 @@ import {
   handleInstructionCall,
   handleStartCall,
 } from './routes/call-routes.js';
+import {
+  startCanonicalGuardianExpirySweep,
+  stopCanonicalGuardianExpirySweep,
+} from './routes/canonical-guardian-expiry-sweep.js';
 import { canonicalChannelAssistantId } from './routes/channel-route-shared.js';
 import {
   handleChannelDeliveryAck,
@@ -341,6 +345,9 @@ export class RuntimeHttpServer {
     startGuardianActionSweep(getGatewayInternalBaseUrl(), this.bearerToken, this.guardianActionCopyGenerator);
     log.info('Guardian action expiry sweep started');
 
+    startCanonicalGuardianExpirySweep();
+    log.info('Canonical guardian request expiry sweep started');
+
     log.info('Running in gateway-only ingress mode. Direct webhook routes disabled.');
     if (!isLoopbackHost(this.hostname)) {
       log.warn('RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.');
@@ -361,6 +368,7 @@ export class RuntimeHttpServer {
     this.pairingStore.stop();
     stopGuardianExpirySweep();
     stopGuardianActionSweep();
+    stopCanonicalGuardianExpirySweep();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;

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/canonical-guardian-expiry-sweep.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical guardian request expiry sweep.
+ *
+ * Periodically scans the `canonical_guardian_requests` table for pending
+ * requests whose `expiresAt` timestamp has passed and transitions them to
+ * the `expired` status.  This ensures that stale requests are cleaned up
+ * even when no follow-up traffic arrives from either the guardian or the
+ * requester.
+ *
+ * Complements the existing sweeps:
+ *   - `calls/guardian-action-sweep.ts` — voice call guardian action expiry
+ *   - `runtime/routes/guardian-expiry-sweep.ts` — channel guardian approval expiry
+ *
+ * Unlike those sweeps, this one operates on the unified canonical domain
+ * (`canonical_guardian_requests`) and does not need to auto-deny pending
+ * interactions or deliver channel notices — the canonical request status
+ * transition is the single source of truth, and consumers (resolvers,
+ * clients polling prompts) observe the expired status directly.
+ */
+
+import {
+  listCanonicalGuardianRequests,
+  resolveCanonicalGuardianRequest,
+} from '../../memory/canonical-guardian-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('canonical-guardian-expiry-sweep');
+
+/** Interval at which the expiry sweep runs (60 seconds). */
+const SWEEP_INTERVAL_MS = 60_000;
+
+/** Timer handle for the sweep so it can be stopped in tests and shutdown. */
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Guard against overlapping sweeps. */
+let sweepInProgress = false;
+
+/**
+ * Sweep all pending canonical guardian requests that have expired.
+ *
+ * Uses CAS resolution (`resolveCanonicalGuardianRequest`) so that a
+ * concurrent decision that wins the race is never overwritten by the
+ * sweep.  Returns the count of requests transitioned to expired.
+ */
+export function sweepExpiredCanonicalGuardianRequests(): number {
+  const pending = listCanonicalGuardianRequests({ status: 'pending' });
+  const now = Date.now();
+  let expiredCount = 0;
+
+  for (const request of pending) {
+    if (!request.expiresAt) continue;
+
+    const expiresAtMs = new Date(request.expiresAt).getTime();
+    if (expiresAtMs >= now) continue;
+
+    // CAS resolve: only transition from 'pending' to 'expired'.
+    // If someone resolved it between our read and this write, the CAS
+    // fails harmlessly (returns null) and we skip the request.
+    const resolved = resolveCanonicalGuardianRequest(request.id, 'pending', {
+      status: 'expired',
+    });
+
+    if (resolved) {
+      expiredCount++;
+      log.info(
+        {
+          event: 'canonical_request_expired',
+          requestId: request.id,
+          kind: request.kind,
+          expiresAt: request.expiresAt,
+        },
+        'Expired canonical guardian request via sweep',
+      );
+    }
+  }
+
+  if (expiredCount > 0) {
+    log.info(
+      { event: 'canonical_expiry_sweep_complete', expiredCount },
+      `Canonical guardian expiry sweep: expired ${expiredCount} request(s)`,
+    );
+  }
+
+  return expiredCount;
+}
+
+/**
+ * Start the periodic canonical guardian expiry sweep. Idempotent — calling
+ * it multiple times reuses the same timer.
+ */
+export function startCanonicalGuardianExpirySweep(): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => {
+    if (sweepInProgress) return;
+    sweepInProgress = true;
+    try {
+      sweepExpiredCanonicalGuardianRequests();
+    } catch (err) {
+      log.error({ err }, 'Canonical guardian expiry sweep failed');
+    } finally {
+      sweepInProgress = false;
+    }
+  }, SWEEP_INTERVAL_MS);
+}
+
+/**
+ * Stop the periodic canonical guardian expiry sweep. Used in tests and
+ * shutdown.
+ */
+export function stopCanonicalGuardianExpirySweep(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+  sweepInProgress = false;
+}

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

@@ -8,6 +8,10 @@ import { CHANNEL_IDS, INTERFACE_IDS, parseChannelId, parseInterfaceId } from '..
 import { mergeToolResults,renderHistoryContent } from '../../daemon/handlers.js';
 import type { ServerMessage } from '../../daemon/ipc-protocol.js';
 import * as attachmentsStore from '../../memory/attachments-store.js';
+import {
+  createCanonicalGuardianRequest,
+  generateCanonicalRequestCode,
+} from '../../memory/canonical-guardian-store.js';
 import {
   getConversationByKey,
   getOrCreateConversation,
@@ -171,6 +175,20 @@ function makeHubPublisher(
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
         },
       });
+
+      // Create a canonical guardian request so IPC/HTTP handlers can find it
+      // via applyCanonicalGuardianDecision.
+      createCanonicalGuardianRequest({
+        id: msg.requestId,
+        kind: 'tool_approval',
+        sourceType: 'desktop',
+        sourceChannel: 'vellum',
+        conversationId,
+        toolName: msg.toolName,
+        status: 'pending',
+        requestCode: generateCanonicalRequestCode(),
+        expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+      });
     } else if (msg.type === 'secret_request') {
       pendingInteractions.register(msg.requestId, {
         session,
@@ -265,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
@@ -335,7 +353,7 @@ export async function handleSendMessage(
       mapping.conversationId,
       content ?? '',
       hasAttachments ? attachmentIds : undefined,
-      { guardianContext: { actorRole: 'guardian', sourceChannel } },
+      { guardianContext: { trustClass: 'guardian', sourceChannel } },
       sourceChannel,
       sourceInterface,
     );