@vellumai/assistant 0.4.4 → 0.4.6

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

@@ -197,19 +197,26 @@ function findPendingCanonicalRequests(
     });
   }
 
-  // For desktop/trusted actors without an externalUserId, query by
-  // conversationId so the NL path can discover pending requests.
+  // Actors without an externalUserId: scope by conversationId so the NL
+  // path can discover pending requests bound to this conversation.
+  // Include guardianPrincipalId filter when available so the guardian only
+  // sees requests they are authorized to act on.
   if (conversationId) {
     return listCanonicalGuardianRequests({
       status: 'pending',
       conversationId,
+      ...(actor.guardianPrincipalId ? { guardianPrincipalId: actor.guardianPrincipalId } : {}),
     });
   }
 
-  // Trusted actors without a conversationId: return all pending requests
-  // so desktop sessions can always discover pending guardian work.
-  if (actor.isTrusted) {
-    return listCanonicalGuardianRequests({ status: 'pending' });
+  // Actors with a guardianPrincipalId but no externalUserId or
+  // conversationId: query by principal so desktop sessions can still
+  // discover pending guardian work via their bound principal.
+  if (actor.guardianPrincipalId) {
+    return listCanonicalGuardianRequests({
+      status: 'pending',
+      guardianPrincipalId: actor.guardianPrincipalId,
+    });
   }
 
   return [];
@@ -301,22 +308,30 @@ export async function routeGuardianReply(
       // silently defaulting to approve_once.
       if (!codeResult.remainingText || codeResult.remainingText.trim().length === 0) {
         // Identity check: only expose request details to the assigned guardian
-        // or trusted (desktop) actors. Mirrors the identity check in
-        // applyCanonicalGuardianDecision to prevent leaking request details
+        // principal. Strict principal equality prevents leaking request details
         // (toolName, questionText) to unauthorized senders.
+        if (!actor.guardianPrincipalId) {
+          return {
+            decisionApplied: false,
+            consumed: true,
+            type: 'code_only_clarification',
+            requestId: request.id,
+            replyText: 'Request not found.',
+          };
+        }
+
         if (
-          request.guardianExternalUserId &&
-          !actor.isTrusted &&
-          actor.externalUserId !== request.guardianExternalUserId
+          request.guardianPrincipalId &&
+          actor.guardianPrincipalId !== request.guardianPrincipalId
         ) {
           log.warn(
             {
-              event: 'router_code_only_identity_mismatch',
+              event: 'router_code_only_principal_mismatch',
               requestId: request.id,
-              expectedGuardian: request.guardianExternalUserId,
-              actualActor: actor.externalUserId,
+              expectedPrincipal: request.guardianPrincipalId,
+              actualPrincipal: actor.guardianPrincipalId,
             },
-            'Code-only clarification blocked: actor identity does not match expected guardian',
+            'Code-only clarification blocked: actor principal does not match request principal',
           );
           return {
             decisionApplied: false,
@@ -492,7 +507,9 @@ export async function routeGuardianReply(
     // Attach the engine's reply text for stale/expired/identity-mismatch cases,
     // but preserve resolver-authored replies (for example verification codes)
     // and explicit resolver-failure text.
-    const hasResolverReplyText = Boolean(result.canonicalResult?.applied && result.canonicalResult.resolverReplyText);
+    const hasResolverReplyText = Boolean(
+      result.canonicalResult?.applied && result.canonicalResult.resolverReplyText,
+    );
     if (engineResult.replyText && result.type !== 'canonical_resolver_failed' && !hasResolverReplyText) {
       result.replyText = engineResult.replyText;
     }

package/src/runtime/guardian-vellum-migration.ts

@@ -5,24 +5,30 @@
  * 'vellum' channel with a guardianPrincipalId. This is required for
  * the identity-bound hatch bootstrap flow.
  *
- * - If a vellum binding already exists, no-op.
+ * - If a vellum binding already exists with a guardianPrincipalId, no-op.
+ * - If a vellum binding exists but lacks guardianPrincipalId, backfill it
+ *   from the binding's guardianExternalUserId.
  * - If no vellum binding exists, creates one with a fresh principal.
  * - Preserves existing guardian bindings for other channels unchanged.
  */
 
+import { eq } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
+import { getDb } from '../memory/db.js';
 import {
   createBinding,
   getActiveBinding,
 } from '../memory/guardian-bindings.js';
+import { channelGuardianBindings } from '../memory/schema.js';
 import { getLogger } from '../util/logger.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
 
 const log = getLogger('guardian-vellum-migration');
 
 /**
- * Ensure a vellum guardian binding exists for the given assistant.
+ * Ensure a vellum guardian binding exists for the given assistant,
+ * with a populated guardianPrincipalId.
  * Called during daemon startup to backfill existing installations.
  *
  * Returns the guardianPrincipalId (existing or newly created).
@@ -30,11 +36,28 @@ const log = getLogger('guardian-vellum-migration');
 export function ensureVellumGuardianBinding(assistantId: string = DAEMON_INTERNAL_ASSISTANT_ID): string {
   const existing = getActiveBinding(assistantId, 'vellum');
   if (existing) {
+    // If the binding exists but is missing guardianPrincipalId, backfill it
+    // from the binding's guardianExternalUserId (the canonical identity).
+    if (!existing.guardianPrincipalId) {
+      const principalId = existing.guardianExternalUserId;
+      const db = getDb();
+      db.update(channelGuardianBindings)
+        .set({ guardianPrincipalId: principalId, updatedAt: Date.now() })
+        .where(eq(channelGuardianBindings.id, existing.id))
+        .run();
+
+      log.info(
+        { assistantId, guardianPrincipalId: principalId },
+        'Backfilled guardianPrincipalId on existing vellum binding',
+      );
+      return principalId;
+    }
+
     log.debug(
-      { assistantId, guardianPrincipalId: existing.guardianExternalUserId },
-      'Vellum guardian binding already exists',
+      { assistantId, guardianPrincipalId: existing.guardianPrincipalId },
+      'Vellum guardian binding already exists with principal',
     );
-    return existing.guardianExternalUserId;
+    return existing.guardianPrincipalId;
   }
 
   const guardianPrincipalId = `vellum-principal-${uuid()}`;
@@ -44,6 +67,7 @@ export function ensureVellumGuardianBinding(assistantId: string = DAEMON_INTERNA
     channel: 'vellum',
     guardianExternalUserId: guardianPrincipalId,
     guardianDeliveryChatId: 'local',
+    guardianPrincipalId,
     verifiedVia: 'startup-migration',
     metadataJson: JSON.stringify({ migratedAt: Date.now() }),
   });

package/src/runtime/http-types.ts

@@ -1,10 +1,6 @@
 /**
  * Shared types for the runtime HTTP server and its route handlers.
  */
-import type {
-  CallPointerMessageContext,
-  ComposeCallPointerMessageOptions,
-} from '../calls/call-pointer-message-composer.js';
 import type { ChannelId, InterfaceId } from '../channels/types.js';
 import type { Session } from '../daemon/session.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
@@ -59,15 +55,6 @@ export type ApprovalConversationGenerator = (
   context: ApprovalConversationContext,
 ) => Promise<ApprovalConversationResult>;
 
-/**
- * Daemon-injected function that generates call pointer copy using a provider.
- * Returns generated text or `null` on failure (caller falls back to deterministic text).
- */
-export type PointerCopyGenerator = (
-  context: CallPointerMessageContext,
-  options?: ComposeCallPointerMessageOptions,
-) => Promise<string | null>;
-
 /**
  * Daemon-injected function that generates guardian action copy using a provider.
  * Returns generated text or `null` on failure (caller falls back to deterministic text).

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

@@ -20,6 +20,7 @@ import {
   resolveGuardianContext,
   toGuardianRuntimeContext,
 } from './guardian-context-resolver.js';
+import { ensureVellumGuardianBinding } from './guardian-vellum-migration.js';
 
 const log = getLogger('local-actor-identity');
 
@@ -42,17 +43,22 @@ export function resolveLocalIpcGuardianContext(
   const binding = getActiveBinding(assistantId, 'vellum');
 
   if (!binding) {
-    // No vellum binding yet (pre-bootstrap). The local user is
-    // inherently the guardian of their own machine, so produce a
-    // guardian context without a binding match. The trust resolver
-    // would classify this as 'unknown' due to no_binding, but for
-    // the local IPC case that is incorrect -- the local macOS user
-    // is always the guardian.
-    log.debug('No vellum guardian binding found; using fallback guardian context for IPC');
-    return {
-      sourceChannel,
-      trustClass: 'guardian',
-    };
+    // No vellum binding yet (pre-bootstrap). Eagerly create one so
+    // downstream code that creates decisionable canonical requests
+    // (tool_approval, pending_question) always has a guardianPrincipalId
+    // available. Without this, createCanonicalGuardianRequest throws
+    // IntegrityError and the request is silently dropped.
+    log.debug('No vellum guardian binding found; bootstrapping binding for IPC');
+    const principalId = ensureVellumGuardianBinding(assistantId);
+
+    // Re-resolve through the shared pipeline now that the binding exists.
+    const guardianCtx = resolveGuardianContext({
+      assistantId,
+      sourceChannel: 'vellum',
+      conversationExternalId: 'local',
+      actorExternalId: principalId,
+    });
+    return toGuardianRuntimeContext(sourceChannel, guardianCtx);
   }
 
   const guardianPrincipalId = binding.guardianExternalUserId;
@@ -66,8 +72,8 @@ export function resolveLocalIpcGuardianContext(
   const guardianCtx = resolveGuardianContext({
     assistantId,
     sourceChannel: 'vellum',
-    externalChatId: 'local',
-    senderExternalUserId: guardianPrincipalId,
+    conversationExternalId: 'local',
+    actorExternalId: guardianPrincipalId,
   });
 
   // Overlay the caller's actual sourceChannel onto the resolved context

package/src/runtime/middleware/actor-token.ts

@@ -116,8 +116,8 @@ export function verifyHttpActorToken(req: Request): ActorTokenVerification {
   const guardianCtx = resolveGuardianContext({
     assistantId,
     sourceChannel: 'vellum',
-    externalChatId: 'local',
-    senderExternalUserId: claims.guardianPrincipalId,
+    conversationExternalId: 'local',
+    actorExternalId: claims.guardianPrincipalId,
   });
 
   const guardianContext = toGuardianRuntimeContext('vellum' as ChannelId, guardianCtx);

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

@@ -34,17 +34,17 @@ export async function handleReplayDeadLetters(req: Request): Promise<Response> {
 export async function handleChannelDeliveryAck(req: Request): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
-    externalChatId?: string;
+    conversationExternalId?: string;
     externalMessageId?: string;
   };
 
-  const { sourceChannel, externalChatId, externalMessageId } = body;
+  const { sourceChannel, conversationExternalId, externalMessageId } = body;
 
   if (!sourceChannel || typeof sourceChannel !== 'string') {
     return httpError('BAD_REQUEST', 'sourceChannel is required', 400);
   }
-  if (!externalChatId || typeof externalChatId !== 'string') {
-    return httpError('BAD_REQUEST', 'externalChatId is required', 400);
+  if (!conversationExternalId || typeof conversationExternalId !== 'string') {
+    return httpError('BAD_REQUEST', 'conversationExternalId is required', 400);
   }
   if (!externalMessageId || typeof externalMessageId !== 'string') {
     return httpError('BAD_REQUEST', 'externalMessageId is required', 400);
@@ -52,7 +52,7 @@ export async function handleChannelDeliveryAck(req: Request): Promise<Response>
 
   const acked = channelDeliveryStore.acknowledgeDelivery(
     sourceChannel,
-    externalChatId,
+    conversationExternalId,
     externalMessageId,
   );
 

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

@@ -86,6 +86,8 @@ async function tryConsumeCanonicalGuardianReply(params: {
   approvalConversationGenerator?: ApprovalConversationGenerator;
   /** Verified actor identity from actor-token middleware. */
   verifiedActorExternalUserId?: string;
+  /** Verified actor principal ID for principal-based authorization. */
+  verifiedActorPrincipalId?: string;
 }): Promise<{ consumed: boolean; messageId?: string }> {
   const {
     conversationId,
@@ -97,6 +99,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
     onEvent,
     approvalConversationGenerator,
     verifiedActorExternalUserId,
+    verifiedActorPrincipalId,
   } = params;
   const trimmedContent = content.trim();
 
@@ -113,12 +116,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
     actor: {
       externalUserId: verifiedActorExternalUserId,
       channel: sourceChannel,
-      // When a verified identity is available, disable the trusted bypass so
-      // that the identity-match checks in applyCanonicalGuardianDecision
-      // actually run. Only fall back to isTrusted when no verified identity
-      // was resolved (defensive — shouldn't happen for vellum since
-      // verification runs upstream).
-      isTrusted: !verifiedActorExternalUserId,
+      guardianPrincipalId: verifiedActorPrincipalId,
     },
     conversationId,
     pendingRequestIds,
@@ -157,7 +155,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
       assistantMessageChannel: sourceChannel,
       userMessageInterface: sourceInterface,
       assistantMessageInterface: sourceInterface,
-      provenanceActorRole: 'guardian' as const,
+      provenanceTrustClass: 'guardian' as const,
     };
 
     const userMessage = createUserMessage(content, attachments);
@@ -345,33 +343,41 @@ function makeHubPublisher(
 
       // Create a canonical guardian request so IPC/HTTP handlers can find it
       // via applyCanonicalGuardianDecision.
-      const guardianContext = session.guardianContext;
-      const sourceChannel = guardianContext?.sourceChannel ?? 'vellum';
-      const canonicalRequest = createCanonicalGuardianRequest({
-        id: msg.requestId,
-        kind: 'tool_approval',
-        sourceType: resolveCanonicalRequestSourceType(sourceChannel),
-        sourceChannel,
-        conversationId,
-        requesterExternalUserId: guardianContext?.requesterExternalUserId,
-        requesterChatId: guardianContext?.requesterChatId,
-        guardianExternalUserId: guardianContext?.guardianExternalUserId,
-        toolName: msg.toolName,
-        status: 'pending',
-        requestCode: generateCanonicalRequestCode(),
-        expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
-      });
-
-      // For trusted-contact sessions, bridge to guardian.question so the
-      // guardian gets notified and can approve via callback/request-code.
-      if (guardianContext) {
-        bridgeConfirmationRequestToGuardian({
-          canonicalRequest,
-          guardianContext,
+      try {
+        const guardianContext = session.guardianContext;
+        const sourceChannel = guardianContext?.sourceChannel ?? 'vellum';
+        const canonicalRequest = createCanonicalGuardianRequest({
+          id: msg.requestId,
+          kind: 'tool_approval',
+          sourceType: resolveCanonicalRequestSourceType(sourceChannel),
+          sourceChannel,
           conversationId,
+          requesterExternalUserId: guardianContext?.requesterExternalUserId,
+          requesterChatId: guardianContext?.requesterChatId,
+          guardianExternalUserId: guardianContext?.guardianExternalUserId,
+          guardianPrincipalId: guardianContext?.guardianPrincipalId ?? undefined,
           toolName: msg.toolName,
-          assistantId: session.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+          status: 'pending',
+          requestCode: generateCanonicalRequestCode(),
+          expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
         });
+
+        // For trusted-contact sessions, bridge to guardian.question so the
+        // guardian gets notified and can approve via callback/request-code.
+        if (guardianContext) {
+          bridgeConfirmationRequestToGuardian({
+            canonicalRequest,
+            guardianContext,
+            conversationId,
+            toolName: msg.toolName,
+            assistantId: session.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+          });
+        }
+      } catch (err) {
+        log.debug(
+          { err, requestId: msg.requestId, conversationId },
+          'Failed to create canonical request from hub publisher',
+        );
       }
     } else if (msg.type === 'secret_request') {
       pendingInteractions.register(msg.requestId, {
@@ -505,12 +511,15 @@ export async function handleSendMessage(
       ? smDeps.resolveAttachments(attachmentIds)
       : [];
 
-    // Resolve the verified actor's external user ID for inline approval
-    // routing. Uses the guardianExternalUserId from the verified context
-    // (actor-token or local-fallback) rather than hardcoding undefined.
+    // Resolve the verified actor's external user ID and principal for inline
+    // approval routing. Uses the guardianExternalUserId and guardianPrincipalId
+    // from the verified context (actor-token or local-fallback).
     const verifiedActorExternalUserId = actorVerification?.ok
       ? actorVerification.guardianContext.guardianExternalUserId
-      : undefined;
+      : session.guardianContext?.guardianExternalUserId;
+    const verifiedActorPrincipalId = actorVerification?.ok
+      ? actorVerification.guardianContext.guardianPrincipalId ?? undefined
+      : session.guardianContext?.guardianPrincipalId ?? undefined;
 
     // Try to consume the message as a canonical guardian approval/rejection reply.
     // On failure, degrade to the existing queue/auto-deny path rather than
@@ -526,6 +535,7 @@ export async function handleSendMessage(
         onEvent,
         approvalConversationGenerator: deps.approvalConversationGenerator,
         verifiedActorExternalUserId,
+        verifiedActorPrincipalId,
       });
       if (inlineReplyResult.consumed) {
         return Response.json(

package/src/runtime/routes/guardian-action-routes.ts

@@ -124,13 +124,19 @@ export async function handleGuardianActionDecision(req: Request, server: ServerW
     ? tokenResult.claims.guardianPrincipalId
     : tokenResult.guardianContext.guardianExternalUserId;
 
+  // Resolve the actor's principal ID: from the token claims if present,
+  // otherwise from the vellum guardian binding (local fallback).
+  const actorPrincipalId = tokenResult.claims
+    ? tokenResult.claims.guardianPrincipalId
+    : tokenResult.guardianContext.guardianPrincipalId ?? undefined;
+
   const canonicalResult = await applyCanonicalGuardianDecision({
     requestId,
     action: action as ApprovalAction,
     actorContext: {
       externalUserId: actorExternalUserId,
       channel: 'vellum',
-      isTrusted: true,
+      guardianPrincipalId: actorPrincipalId,
     },
     userText: undefined,
   });