@vellumai/assistant 0.4.3 → 0.4.4

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

@@ -47,7 +47,7 @@ import {
 } from '../channel-guardian-service.js';
 import { getTransport } from '../channel-invite-transport.js';
 import { deliverChannelReply } from '../gateway-client.js';
-import { resolveGuardianContext } from '../guardian-context-resolver.js';
+import { resolveGuardianContext, resolveRoutingState } from '../guardian-context-resolver.js';
 import { routeGuardianReply } from '../guardian-reply-router.js';
 import {
   composeChannelVerifyReply,
@@ -415,6 +415,7 @@ export async function handleChannelInbound(
                 senderExternalUserId: canonicalSenderId ?? rawSenderId,
                 senderName: body.senderName,
                 senderUsername: body.senderUsername,
+                previousMemberStatus: resolvedMember.status,
               });
               guardianNotified = accessResult.notified;
             } catch (err) {
@@ -1347,6 +1348,13 @@ interface BackgroundProcessingParams {
 const TELEGRAM_TYPING_INTERVAL_MS = 4_000;
 const PENDING_APPROVAL_POLL_INTERVAL_MS = 300;
 
+// Module-level map tracking which approval requestIds have already been
+// notified to trusted contacts. Maps requestId -> conversationId so that
+// cleanup can be scoped to the owning conversation's poller, preventing
+// concurrent pollers from different conversations from evicting each
+// other's entries.
+const globalNotifiedApprovalRequestIds = new Map<string, string>();
+
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1478,6 +1486,126 @@ function startPendingApprovalPromptWatcher(params: {
   };
 }
 
+/**
+ * Resolve a human-readable guardian name from the guardian binding metadata.
+ * Returns the display name, username (prefixed with @), or undefined if
+ * no name is available.
+ */
+function resolveGuardianDisplayName(
+  assistantId: string,
+  sourceChannel: ChannelId,
+): string | undefined {
+  const binding = getGuardianBinding(assistantId, sourceChannel);
+  if (!binding?.metadataJson) return undefined;
+  try {
+    const parsed = JSON.parse(binding.metadataJson) as Record<string, unknown>;
+    if (typeof parsed.displayName === 'string' && parsed.displayName.trim().length > 0) {
+      return parsed.displayName.trim();
+    }
+    if (typeof parsed.username === 'string' && parsed.username.trim().length > 0) {
+      return `@${parsed.username.trim()}`;
+    }
+  } catch {
+    // ignore malformed metadata
+  }
+  return undefined;
+}
+
+/**
+ * Start a poller that sends a one-shot "waiting for guardian approval" message
+ * to the trusted contact when a confirmation_request enters guardian approval
+ * wait. Deduplicates by requestId so each request only produces one message.
+ *
+ * Only activates for trusted-contact actors with a resolvable guardian route.
+ */
+function startTrustedContactApprovalNotifier(params: {
+  conversationId: string;
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  guardianTrustClass: GuardianContext['trustClass'];
+  guardianExternalUserId?: string;
+  replyCallbackUrl: string;
+  bearerToken?: string;
+  assistantId?: string;
+}): () => void {
+  const {
+    conversationId,
+    sourceChannel,
+    externalChatId,
+    guardianTrustClass,
+    guardianExternalUserId,
+    replyCallbackUrl,
+    bearerToken,
+    assistantId,
+  } = params;
+
+  // Only notify trusted contacts who have a resolvable guardian route.
+  if (guardianTrustClass !== 'trusted_contact' || !guardianExternalUserId) {
+    return () => {};
+  }
+
+  let active = true;
+
+  const poll = async (): Promise<void> => {
+    while (active) {
+      try {
+        const pending = getApprovalInfoByConversation(conversationId);
+        const info = pending[0];
+
+        // Clean up resolved requests from the module-level dedupe map.
+        // Only remove entries that belong to THIS conversation — other
+        // conversations' pollers own their own entries. Without this
+        // scoping, concurrent pollers would evict each other's request
+        // IDs and cause duplicate notifications.
+        const currentPendingIds = new Set(pending.map(p => p.requestId));
+        for (const [rid, cid] of globalNotifiedApprovalRequestIds) {
+          if (cid === conversationId && !currentPendingIds.has(rid)) {
+            globalNotifiedApprovalRequestIds.delete(rid);
+          }
+        }
+
+        if (info && !globalNotifiedApprovalRequestIds.has(info.requestId)) {
+          globalNotifiedApprovalRequestIds.set(info.requestId, conversationId);
+          const guardianName = resolveGuardianDisplayName(
+            assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+            sourceChannel,
+          );
+          const waitingText = guardianName
+            ? `Waiting for ${guardianName}'s approval...`
+            : 'Waiting for your guardian\'s approval...';
+          try {
+            await deliverChannelReply(replyCallbackUrl, {
+              chatId: externalChatId,
+              text: waitingText,
+              assistantId: assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+            }, bearerToken);
+          } catch (err) {
+            log.warn({ err, conversationId }, 'Failed to deliver trusted-contact pending-approval notification');
+            // Remove from notified set so delivery is retried on next poll
+            globalNotifiedApprovalRequestIds.delete(info.requestId);
+          }
+        }
+      } catch (err) {
+        log.warn({ err, conversationId }, 'Trusted-contact approval notifier poll failed');
+      }
+      await delay(PENDING_APPROVAL_POLL_INTERVAL_MS);
+    }
+  };
+
+  void poll();
+  return () => {
+    active = false;
+
+    // Evict all dedupe entries owned by this conversation so the
+    // module-level map doesn't grow unboundedly after the poller stops.
+    for (const [rid, cid] of globalNotifiedApprovalRequestIds) {
+      if (cid === conversationId) {
+        globalNotifiedApprovalRequestIds.delete(rid);
+      }
+    }
+  };
+}
+
 function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
   const {
     processMessage,
@@ -1520,6 +1648,18 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
         approvalCopyGenerator,
       })
       : undefined;
+    const stopTcApprovalNotifier = replyCallbackUrl
+      ? startTrustedContactApprovalNotifier({
+        conversationId,
+        sourceChannel,
+        externalChatId,
+        guardianTrustClass: guardianCtx.trustClass,
+        guardianExternalUserId: guardianCtx.guardianExternalUserId,
+        replyCallbackUrl,
+        bearerToken,
+        assistantId,
+      })
+      : undefined;
 
     try {
       const cmdIntent = commandIntent && typeof commandIntent.type === 'string'
@@ -1537,7 +1677,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
           },
           assistantId,
           guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
-          isInteractive: guardianCtx.trustClass === 'guardian',
+          isInteractive: resolveRoutingState(guardianCtx).promptWaitingAllowed,
           ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
         },
         sourceChannel,
@@ -1565,6 +1705,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     } finally {
       stopTypingHeartbeat?.();
       stopApprovalWatcher?.();
+      stopTcApprovalNotifier?.();
     }
   })();
 }

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

@@ -144,16 +144,15 @@ export function handleClearSlackChannelConfig(): Response {
 /**
  * POST /v1/integrations/guardian/challenge
  *
- * Body: { channel?: ChannelId; assistantId?: string; rebind?: boolean; sessionId?: string }
+ * Body: { channel?: ChannelId; rebind?: boolean; sessionId?: string }
  */
 export async function handleCreateGuardianChallenge(req: Request): Promise<Response> {
   const body = (await req.json()) as {
     channel?: ChannelId;
-    assistantId?: string;
     rebind?: boolean;
     sessionId?: string;
   };
-  const result = createGuardianChallenge(body.channel, body.assistantId, body.rebind, body.sessionId);
+  const result = createGuardianChallenge(body.channel, body.rebind, body.sessionId);
   const status = result.success ? 200 : 400;
   return Response.json(result, { status });
 }
@@ -161,12 +160,11 @@ export async function handleCreateGuardianChallenge(req: Request): Promise<Respo
 /**
  * GET /v1/integrations/guardian/status
  *
- * Query params: channel?, assistantId?
+ * Query params: channel?
  */
 export function handleGetGuardianStatus(url: URL): Response {
   const channel = (url.searchParams.get('channel') as ChannelId | null) ?? undefined;
-  const assistantId = url.searchParams.get('assistantId') ?? undefined;
-  const result = getGuardianStatus(channel, assistantId);
+  const result = getGuardianStatus(channel);
   return Response.json(result);
 }
 
@@ -177,13 +175,12 @@ export function handleGetGuardianStatus(url: URL): Response {
 /**
  * POST /v1/integrations/guardian/outbound/start
  *
- * Body: { channel: ChannelId; destination?: string; assistantId?: string; rebind?: boolean; originConversationId?: string }
+ * Body: { channel: ChannelId; destination?: string; rebind?: boolean; originConversationId?: string }
  */
 export async function handleStartOutbound(req: Request): Promise<Response> {
   const body = (await req.json()) as {
     channel?: ChannelId;
     destination?: string;
-    assistantId?: string;
     rebind?: boolean;
     originConversationId?: string;
   };
@@ -209,7 +206,6 @@ export async function handleStartOutbound(req: Request): Promise<Response> {
   const result = startOutbound({
     channel: body.channel,
     destination: body.destination,
-    assistantId: body.assistantId,
     rebind: body.rebind,
     originConversationId: body.originConversationId,
   });
@@ -225,12 +221,11 @@ export async function handleStartOutbound(req: Request): Promise<Response> {
 /**
  * POST /v1/integrations/guardian/outbound/resend
  *
- * Body: { channel: ChannelId; assistantId?: string; originConversationId?: string }
+ * Body: { channel: ChannelId; originConversationId?: string }
  */
 export async function handleResendOutbound(req: Request): Promise<Response> {
   const body = (await req.json()) as {
     channel?: ChannelId;
-    assistantId?: string;
     originConversationId?: string;
   };
   if (!body.channel) {
@@ -238,7 +233,6 @@ export async function handleResendOutbound(req: Request): Promise<Response> {
   }
   const result = resendOutbound({
     channel: body.channel,
-    assistantId: body.assistantId,
     originConversationId: body.originConversationId,
   });
   const status = result.success ? 200 : (result.error === 'rate_limited' ? 429 : 400);
@@ -248,19 +242,17 @@ export async function handleResendOutbound(req: Request): Promise<Response> {
 /**
  * POST /v1/integrations/guardian/outbound/cancel
  *
- * Body: { channel: ChannelId; assistantId?: string }
+ * Body: { channel: ChannelId }
  */
 export async function handleCancelOutbound(req: Request): Promise<Response> {
   const body = (await req.json()) as {
     channel?: ChannelId;
-    assistantId?: string;
   };
   if (!body.channel) {
     return httpError('BAD_REQUEST', 'The "channel" field is required.', 400);
   }
   const result = cancelOutbound({
     channel: body.channel,
-    assistantId: body.assistantId,
   });
   const status = result.success ? 200 : 400;
   return Response.json(result, { status });

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

@@ -10,10 +10,127 @@ import {
 import type { ServerMessage } from '../../daemon/ipc-contract.js';
 import { PairingStore } from '../../daemon/pairing-store.js';
 import { getLogger } from '../../util/logger.js';
+import { mintActorToken } from '../actor-token-service.js';
+import {
+  createActorTokenRecord,
+  revokeByDeviceBinding,
+} from '../actor-token-store.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import { ensureVellumGuardianBinding } from '../guardian-vellum-migration.js';
 import { httpError } from '../http-errors.js';
 
 const log = getLogger('runtime-http');
 
+/**
+ * Mint an actor token for a paired device if a vellum guardian principal exists.
+ * Returns the raw actor token string, or null if no vellum binding exists.
+ *
+ * NOTE: This function MUST remain synchronous — the mintingInFlight guard depends on it.
+ */
+function mintPairingActorToken(deviceId: string, platform: string): string | null {
+  try {
+    const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+    // Pairing can run before a local client has touched the actor-token
+    // bootstrap path. Ensure the vellum guardian principal exists so iOS
+    // pairings always have a mint target.
+    const guardianPrincipalId = ensureVellumGuardianBinding(assistantId);
+    const hashedDeviceId = hashDeviceId(deviceId);
+
+    // Revoke previous tokens for this device
+    revokeByDeviceBinding(assistantId, guardianPrincipalId, hashedDeviceId);
+
+    const { token, tokenHash, claims } = mintActorToken({
+      assistantId,
+      platform,
+      deviceId,
+      guardianPrincipalId,
+    });
+
+    createActorTokenRecord({
+      tokenHash,
+      assistantId,
+      guardianPrincipalId,
+      hashedDeviceId,
+      platform,
+      issuedAt: claims.iat,
+      expiresAt: claims.exp,
+    });
+
+    log.info({ assistantId, platform }, 'Minted actor token during pairing');
+    return token;
+  } catch (err) {
+    log.warn({ err }, 'Failed to mint actor token during pairing — continuing without it');
+    return null;
+  }
+}
+
+/**
+ * Transient in-memory map of pairingRequestId -> { deviceId, createdAt }.
+ * Stored when a pairing request is initiated (we have the raw deviceId)
+ * so the token can be minted later when the pairing is actually approved.
+ * Entries include a timestamp so stale entries can be swept if the
+ * corresponding pairing expires without an explicit deny.
+ */
+const PENDING_DEVICE_ID_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const pendingDeviceIds = new Map<string, { deviceId: string; createdAt: number }>();
+
+/**
+ * Transient in-memory map of pairingRequestId -> { actorToken, approvedAt }.
+ * Populated when a pairing is approved and the actor token is minted.
+ * Entries are kept for TOKEN_RETRIEVAL_TTL_MS after approval so that
+ * subsequent polls can still retrieve the token if the first response
+ * was dropped or timed out.
+ */
+const TOKEN_RETRIEVAL_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const approvedActorTokens = new Map<string, { actorToken: string; approvedAt: number }>();
+
+/**
+ * Sweep stale entries from the approved actor tokens map.
+ * Called lazily on each status poll.
+ */
+function sweepApprovedTokens(): void {
+  const now = Date.now();
+  for (const [id, entry] of approvedActorTokens) {
+    if (now - entry.approvedAt > TOKEN_RETRIEVAL_TTL_MS) {
+      approvedActorTokens.delete(id);
+    }
+  }
+}
+
+/**
+ * Sweep stale entries from the pending device IDs map.
+ * Entries older than PENDING_DEVICE_ID_TTL_MS are removed to prevent
+ * unbounded accumulation of raw device identifiers when pairings expire
+ * without an explicit deny.
+ */
+function sweepPendingDeviceIds(): void {
+  const now = Date.now();
+  for (const [id, entry] of pendingDeviceIds) {
+    if (now - entry.createdAt > PENDING_DEVICE_ID_TTL_MS) {
+      pendingDeviceIds.delete(id);
+    }
+  }
+}
+
+/**
+ * In-flight mint guard — prevents overlapping status polls from triggering
+ * concurrent token mints for the same pairing request. The second mint
+ * would revoke the first token, leaving the client with an invalid token.
+ *
+ * MUST remain synchronous — async would break this concurrency guard.
+ */
+const mintingInFlight = new Set<string>();
+
+/**
+ * Clean up all transient pairing state for a given request.
+ * Called when pairing is denied or otherwise finalized.
+ */
+export function cleanupPairingState(pairingRequestId: string): void {
+  pendingDeviceIds.delete(pairingRequestId);
+  approvedActorTokens.delete(pairingRequestId);
+  mintingInFlight.delete(pairingRequestId);
+}
+
 export interface PairingHandlerContext {
   pairingStore: PairingStore;
   bearerToken: string | undefined;
@@ -90,15 +207,22 @@ export async function handlePairingRequest(req: Request, ctx: PairingHandlerCont
       refreshDevice(hashedDeviceId, deviceName);
       ctx.pairingStore.approve(pairingRequestId, ctx.bearerToken);
       log.info({ pairingRequestId, hashedDeviceId }, 'Auto-approved allowlisted device');
+      const actorToken = mintPairingActorToken(deviceId, 'ios');
       return Response.json({
         status: 'approved',
         bearerToken: ctx.bearerToken,
         gatewayUrl: entry.gatewayUrl,
         localLanUrl: entry.localLanUrl,
         ...(ctx.featureFlagToken ? { featureFlagToken: ctx.featureFlagToken } : {}),
+        ...(actorToken ? { actorToken } : {}),
       });
     }
 
+    // Store the raw deviceId transiently so we can mint the actor token
+    // later when the pairing is actually approved (avoids revoking existing
+    // tokens and creating DB records for unapproved devices).
+    pendingDeviceIds.set(pairingRequestId, { deviceId, createdAt: Date.now() });
+
     // Send IPC to macOS to show approval prompt
     if (ctx.pairingBroadcast) {
       ctx.pairingBroadcast({
@@ -124,6 +248,7 @@ export function handlePairingStatus(url: URL, ctx: PairingHandlerContext): Respo
   const id = url.searchParams.get('id') ?? '';
   // Note: secret is redacted from logs
   const secret = url.searchParams.get('secret') ?? '';
+  const deviceId = (url.searchParams.get('deviceId') ?? '').trim();
 
   if (!id || !secret) {
     return httpError('BAD_REQUEST', 'Missing required params: id, secret', 400);
@@ -133,18 +258,56 @@ export function handlePairingStatus(url: URL, ctx: PairingHandlerContext): Respo
     return httpError('FORBIDDEN', 'Forbidden', 403);
   }
 
+  // Sweep stale transient entries on every poll — not just approved ones —
+  // so abandoned pairing attempts don't accumulate indefinitely.
+  sweepApprovedTokens();
+  sweepPendingDeviceIds();
+
   const entry = ctx.pairingStore.get(id);
   if (!entry) {
+    // Pairing expired or was swept — clean up any lingering pending device ID
+    pendingDeviceIds.delete(id);
     return httpError('NOT_FOUND', 'Not found', 404);
   }
 
   if (entry.status === 'approved') {
+    // Mint the actor token on first approved poll if we still have the
+    // raw deviceId from the pairing request. Once minted, the token is
+    // cached in approvedActorTokens with a TTL so subsequent polls can
+    // still retrieve it if the first response was dropped.
+    // The pending deviceId is only removed after a successful mint so
+    // transient failures allow retries on subsequent polls.
+    let tokenEntry = approvedActorTokens.get(id);
+    if (!tokenEntry && !mintingInFlight.has(id)) {
+      const pending = pendingDeviceIds.get(id);
+      const deviceIdMatchesEntry = Boolean(
+        deviceId
+        && entry.hashedDeviceId
+        && hashDeviceId(deviceId) === entry.hashedDeviceId,
+      );
+      const mintDeviceId = pending?.deviceId ?? (deviceIdMatchesEntry ? deviceId : undefined);
+      if (mintDeviceId) {
+        mintingInFlight.add(id);
+        try {
+          const actorToken = mintPairingActorToken(mintDeviceId, 'ios');
+          if (actorToken) {
+            pendingDeviceIds.delete(id);
+            tokenEntry = { actorToken, approvedAt: Date.now() };
+            approvedActorTokens.set(id, tokenEntry);
+          }
+        } finally {
+          mintingInFlight.delete(id);
+        }
+      }
+    }
+
     return Response.json({
       status: 'approved',
       bearerToken: entry.bearerToken,
       gatewayUrl: entry.gatewayUrl,
       localLanUrl: entry.localLanUrl,
       ...(ctx.featureFlagToken ? { featureFlagToken: ctx.featureFlagToken } : {}),
+      ...(tokenEntry ? { actorToken: tokenEntry.actorToken } : {}),
     });
   }