@vellumai/assistant 0.4.4 → 0.4.6

package/src/__tests__/skill-projection.benchmark.test.ts

@@ -22,6 +22,27 @@ mock.module('../util/logger.js', () => ({
     new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
 }));
 
+// Mock config loader and feature flags to avoid filesystem reads on CI.
+// getConfig returns a minimal config; all feature flags default to enabled.
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({}),
+  loadConfig: () => ({}),
+  applyNestedDefaults: (c: unknown) => c,
+  saveConfig: () => {},
+  invalidateConfigCache: () => {},
+  loadRawConfig: () => ({}),
+  saveRawConfig: () => {},
+  getNestedValue: () => undefined,
+  setNestedValue: () => {},
+  API_KEY_PROVIDERS: [],
+}));
+
+mock.module('../config/assistant-feature-flags.js', () => ({
+  isAssistantFeatureFlagEnabled: () => true,
+  loadDefaultsRegistry: () => ({}),
+  getFeatureFlagDefault: () => true,
+}));
+
 // Skill catalog: returns a configurable list of fake skills
 let catalogSkillIds: string[] = [];
 mock.module('../config/skills.js', () => ({
@@ -35,6 +56,21 @@ mock.module('../config/skills.js', () => ({
       bundled: false,
       userInvocable: false,
     })),
+  // Needed by transitive deps (skill-state.ts imports this)
+  checkSkillRequirements: () => ({ eligible: true, missing: {} }),
+  getSkillsDir: () => '/tmp/fake-skills',
+  getBundledSkillsDir: () => '/tmp/fake-bundled-skills',
+  resolveSkillSelector: () => ({ found: false }),
+  loadSkillBySelector: () => ({ found: false }),
+  readCachedSkillIcon: () => undefined,
+}));
+
+// Mock skill-state.js to break the transitive import chain — the benchmark
+// only needs skillFlagKey and doesn't exercise resolveSkillStates.
+mock.module('../config/skill-state.js', () => ({
+  skillFlagKey: (id: string) => `feature_flags.${id}.enabled`,
+  isSkillFeatureEnabled: () => true,
+  resolveSkillStates: () => [],
 }));
 
 mock.module('../skills/tool-manifest.js', () => ({
@@ -91,9 +127,37 @@ mock.module('../tools/skills/skill-tool-factory.js', () => ({
     })),
 }));
 
-// existsSync mock — TOOLS.json always exists for fake skills
+// node:fs mock — TOOLS.json always exists for fake skills.
+// Must include ALL named exports that any transitive dep imports, otherwise
+// Bun's module resolver throws "Export named '…' not found".
+const statStub = () => ({ isSymbolicLink: () => false, isDirectory: () => false, isFile: () => true });
 mock.module('node:fs', () => ({
-  existsSync: () => true,
+  existsSync: (p: string) => typeof p === 'string' && p.endsWith('TOOLS.json'),
+  readFileSync: () => '',
+  lstatSync: statStub,
+  readdirSync: () => [],
+  realpathSync: (p: string) => p,
+  statSync: statStub,
+  statfsSync: statStub,
+  mkdirSync: () => undefined,
+  mkdtempSync: () => '/tmp/mock',
+  renameSync: () => undefined,
+  rmSync: () => undefined,
+  unlinkSync: () => undefined,
+  writeFileSync: () => undefined,
+  appendFileSync: () => undefined,
+  copyFileSync: () => undefined,
+  cpSync: () => undefined,
+  chmodSync: () => undefined,
+  symlinkSync: () => undefined,
+  utimesSync: () => undefined,
+  openSync: () => 0,
+  closeSync: () => undefined,
+  readSync: () => 0,
+  createWriteStream: () => ({ write: () => true, end: () => {}, on: () => {} }),
+  watch: () => ({ close: () => {} }),
+  Dirent: class {},
+  Stats: class {},
 }));
 
 const benchmarkRegistry = new Map<string, unknown>();

package/src/__tests__/system-prompt.test.ts

@@ -57,6 +57,7 @@ mock.module('../config/loader.js', () => ({
 
 mock.module('../config/user-reference.js', () => ({
   resolveUserReference: () => 'John',
+  resolveUserPronouns: () => null,
 }));
 
 // Import after mock

package/src/__tests__/tool-approval-handler.test.ts

@@ -286,7 +286,7 @@ describe('ToolApprovalHandler / pre-exec gate grant check', () => {
     expect(result.allowed).toBe(true);
   });
 
-  test('undefined actor role (desktop/trusted) bypasses grant check', async () => {
+  test('undefined actor role (desktop) bypasses grant check', async () => {
     const toolName = 'bash';
     const input = { command: 'deploy' };
 

package/src/__tests__/tool-grant-request-escalation.test.ts

@@ -162,7 +162,7 @@ function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: 'guardian-1',
     channel: 'telegram',
-    isTrusted: false,
+    guardianPrincipalId: 'test-principal-id',
     ...overrides,
   };
 }
@@ -361,6 +361,7 @@ describe('applyCanonicalGuardianDecision / tool_grant_request', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:testdigest',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -390,6 +391,7 @@ describe('applyCanonicalGuardianDecision / tool_grant_request', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:testdigest',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -417,6 +419,7 @@ describe('applyCanonicalGuardianDecision / tool_grant_request', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:testdigest',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -425,7 +428,7 @@ describe('applyCanonicalGuardianDecision / tool_grant_request', () => {
     const result = await applyCanonicalGuardianDecision({
       requestId: req.id,
       action: 'approve_once',
-      actorContext: guardianActor({ externalUserId: 'imposter-99' }),
+      actorContext: guardianActor({ guardianPrincipalId: 'imposter-principal' }),
     });
 
     expect(result.applied).toBe(false);
@@ -564,6 +567,7 @@ describe('inline wait-and-resume', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:waitgrant',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -606,6 +610,7 @@ describe('inline wait-and-resume', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:denywait',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -645,6 +650,7 @@ describe('inline wait-and-resume', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:timeoutwait',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -679,6 +685,7 @@ describe('inline wait-and-resume', () => {
       conversationId: 'conv-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:abortwait',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),

package/src/__tests__/trusted-contact-inline-approval-integration.test.ts

@@ -221,7 +221,7 @@ function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: 'guardian-1',
     channel: 'telegram',
-    isTrusted: false,
+    guardianPrincipalId: 'test-principal-id',
     ...overrides,
   };
 }
@@ -381,6 +381,7 @@ describe('(b) prompt-path flow: confirmation_request bridges to guardian', () =>
       conversationId: 'conv-bridge-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       status: 'pending',
       expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
@@ -419,6 +420,7 @@ describe('(b) prompt-path flow: confirmation_request bridges to guardian', () =>
       conversationId: 'conv-unified-1',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       status: 'pending',
       expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
@@ -508,6 +510,7 @@ describe('(c) no-binding flow: trusted contact fails fast without guardian bindi
       conversationId: 'conv-nobinding',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       status: 'pending',
       expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
@@ -607,6 +610,7 @@ describe('(d) unknown actor flow: fail-closed with no interactive approval', ()
       conversationId: 'conv-unknown',
       requesterExternalUserId: 'unknown-user',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       status: 'pending',
       expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
@@ -794,6 +798,7 @@ describe('(f) timeout/stale flow: stale guardian decision after inline wait time
       requesterExternalUserId: 'requester-1',
       requesterChatId: 'requester-chat-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:stale',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -842,6 +847,7 @@ describe('(f) timeout/stale flow: stale guardian decision after inline wait time
       requesterExternalUserId: 'requester-1',
       requesterChatId: 'requester-chat-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       inputDigest: 'sha256:fresh',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -974,6 +980,7 @@ describe('cross-milestone integration checks', () => {
       conversationId: 'conv-consistency',
       requesterExternalUserId: 'requester-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: 'test-principal-id',
       toolName: 'bash',
       status: 'pending',
       expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),

package/src/__tests__/trusted-contact-lifecycle-notifications.test.ts

@@ -125,12 +125,12 @@ function buildInboundRequest(overrides: Record<string, unknown> = {}): Request {
   const body: Record<string, unknown> = {
     sourceChannel: 'telegram',
     interface: 'telegram',
-    externalChatId: 'chat-123',
+    conversationExternalId: 'chat-123',
     externalMessageId: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     content: 'Hello',
-    senderExternalUserId: 'requester-user-456',
-    senderName: 'Alice Requester',
-    senderUsername: 'alice_req',
+    actorExternalId: 'requester-user-456',
+    actorDisplayName: 'Alice Requester',
+    actorUsername: 'alice_req',
     replyCallbackUrl: 'http://localhost:7830/deliver/telegram',
     ...overrides,
   };
@@ -192,9 +192,9 @@ describe('trusted contact lifecycle notification signals', () => {
 
     // Guardian denies via callback button
     const guardianReq = buildInboundRequest({
-      externalChatId: 'guardian-chat-789',
-      senderExternalUserId: 'guardian-user-789',
-      senderName: 'Guardian',
+      conversationExternalId: 'guardian-chat-789',
+      actorExternalId: 'guardian-user-789',
+      actorDisplayName: 'Guardian',
       content: '',
       callbackData: `apr:${testRequestId}:reject`,
     });
@@ -267,9 +267,9 @@ describe('trusted contact lifecycle notification signals', () => {
 
     // Guardian approves via callback button
     const guardianReq = buildInboundRequest({
-      externalChatId: 'guardian-chat-789',
-      senderExternalUserId: 'guardian-user-789',
-      senderName: 'Guardian',
+      conversationExternalId: 'guardian-chat-789',
+      actorExternalId: 'guardian-user-789',
+      actorDisplayName: 'Guardian',
       content: '',
       callbackData: `apr:${testRequestId}:approve_once`,
     });
@@ -340,9 +340,9 @@ describe('trusted contact lifecycle notification signals', () => {
 
     // All guardian_decision signals include the approval ID in the dedupe key
     const guardianReq = buildInboundRequest({
-      externalChatId: 'guardian-chat-789',
-      senderExternalUserId: 'guardian-user-789',
-      senderName: 'Guardian',
+      conversationExternalId: 'guardian-chat-789',
+      actorExternalId: 'guardian-user-789',
+      actorDisplayName: 'Guardian',
       content: '',
       callbackData: `apr:${testRequestId}:reject`,
     });
@@ -389,8 +389,8 @@ describe('trusted contact activated notification signal', () => {
     // Requester enters the verification code
     const verifyReq = buildInboundRequest({
       content: session.secret,
-      externalChatId: 'chat-123',
-      senderExternalUserId: 'requester-user-456',
+      conversationExternalId: 'chat-123',
+      actorExternalId: 'requester-user-456',
     });
 
     await handleChannelInbound(verifyReq, undefined, TEST_BEARER_TOKEN);
@@ -449,9 +449,9 @@ describe('trusted contact activated notification signal', () => {
 
     const verifyReq = buildInboundRequest({
       content: session.secret,
-      externalChatId: 'chat-123',
-      senderExternalUserId: 'requester-user-456',
-      senderName: 'Noa Flaherty',
+      conversationExternalId: 'chat-123',
+      actorExternalId: 'requester-user-456',
+      actorDisplayName: 'Noa Flaherty',
     });
 
     await handleChannelInbound(verifyReq, undefined, TEST_BEARER_TOKEN);
@@ -476,8 +476,8 @@ describe('trusted contact activated notification signal', () => {
     // "Guardian" enters the verification code
     const verifyReq = buildInboundRequest({
       content: secret,
-      externalChatId: 'guardian-chat-new',
-      senderExternalUserId: 'guardian-user-new',
+      conversationExternalId: 'guardian-chat-new',
+      actorExternalId: 'guardian-user-new',
     });
 
     await handleChannelInbound(verifyReq, undefined, TEST_BEARER_TOKEN);
@@ -520,8 +520,8 @@ describe('trusted contact activated notification signal', () => {
 
     const verifyReq = buildInboundRequest({
       content: session.secret,
-      externalChatId: 'chat-123',
-      senderExternalUserId: 'requester-user-456',
+      conversationExternalId: 'chat-123',
+      actorExternalId: 'requester-user-456',
     });
 
     await handleChannelInbound(verifyReq, undefined, TEST_BEARER_TOKEN);

package/src/__tests__/trusted-contact-multichannel.test.ts

@@ -160,12 +160,12 @@ function buildInboundRequest(
   const body: Record<string, unknown> = {
     sourceChannel: config.channel,
     interface: config.channel,
-    externalChatId: config.externalChatId,
+    conversationExternalId: config.externalChatId,
     externalMessageId: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     content: 'Hello, can I use this assistant?',
-    senderExternalUserId: config.senderExternalUserId,
-    senderName: 'Test Requester',
-    senderUsername: 'test_requester',
+    actorExternalId: config.senderExternalUserId,
+    actorDisplayName: 'Test Requester',
+    actorUsername: 'test_requester',
     replyCallbackUrl: `http://localhost:7830${config.deliverEndpoint}`,
     ...overrides,
   };

package/src/__tests__/trusted-contact-verification.test.ts

@@ -158,8 +158,8 @@ describe('trusted contact verification → member activation', () => {
     const trust = resolveActorTrust({
       assistantId: 'self',
       sourceChannel: 'telegram',
-      externalChatId: 'requester-chat-jeff',
-      senderExternalUserId: 'requester-user-jeff',
+      conversationExternalId: 'requester-chat-jeff',
+      actorExternalId: 'requester-user-jeff',
     });
 
     expect(trust.trustClass).toBe('trusted_contact');
@@ -184,10 +184,10 @@ describe('trusted contact verification → member activation', () => {
     const trust = resolveActorTrust({
       assistantId: 'self',
       sourceChannel: 'telegram',
-      externalChatId: 'requester-chat-jeff-priority',
-      senderExternalUserId: 'requester-user-jeff-priority',
-      senderUsername: 'jeffrey_telegram',
-      senderDisplayName: 'Jeffrey',
+      conversationExternalId: 'requester-chat-jeff-priority',
+      actorExternalId: 'requester-user-jeff-priority',
+      actorUsername: 'jeffrey_telegram',
+      actorDisplayName: 'Jeffrey',
     });
 
     expect(trust.trustClass).toBe('trusted_contact');
@@ -216,10 +216,10 @@ describe('trusted contact verification → member activation', () => {
     const trust = resolveActorTrust({
       assistantId: 'self',
       sourceChannel: 'telegram',
-      externalChatId: 'shared-group-chat',
-      senderExternalUserId: 'actual-sender-in-group',
-      senderUsername: 'actual_sender_handle',
-      senderDisplayName: 'Actual Sender',
+      conversationExternalId: 'shared-group-chat',
+      actorExternalId: 'actual-sender-in-group',
+      actorUsername: 'actual_sender_handle',
+      actorDisplayName: 'Actual Sender',
     });
 
     // The member record returned by findMember matched on chatId but belongs

package/src/approvals/guardian-decision-primitive.ts

@@ -18,7 +18,8 @@
  *   9. Kind-specific resolver dispatch via the resolver registry
  *
  * Security invariants enforced here:
- *   - Decision application is identity-bound to expected guardian identity
+ *   - Decision authorization is purely principal-based:
+ *     actor.guardianPrincipalId === request.guardianPrincipalId (strict equality)
  *   - Decisions are first-response-wins (CAS-like stale protection)
  *   - `approve_always` is rejected/downgraded for guardian-on-behalf requests
  *   - Scoped grant minting only on explicit approve for requests with tool metadata
@@ -352,44 +353,46 @@ export async function applyCanonicalGuardianDecision(
     return { applied: false, reason: 'invalid_action', detail: `invalid action: ${action}` };
   }
 
-  // 2c. Validate identity: actor must match guardian_external_user_id
-  // unless the actor is trusted (desktop).
-  //
-  // Channel tool-approval requests must always be identity-bound. Treat
-  // missing guardianExternalUserId as unauthorized (fail-closed) so a
-  // non-guardian actor can never approve an unbound request.
-  if (
-    !actorContext.isTrusted &&
-    request.kind === 'tool_approval' &&
-    !request.guardianExternalUserId
-  ) {
+  // 2c. Principal-based authorization: actor.guardianPrincipalId must match
+  // request.guardianPrincipalId for any applied decision. This is the single
+  // authorization gate — principal identity must always match.
+
+  if (!request.guardianPrincipalId) {
     log.warn(
       {
-        event: 'canonical_decision_missing_guardian_binding',
+        event: 'canonical_decision_missing_request_principal',
         requestId,
         kind: request.kind,
         sourceType: request.sourceType,
       },
-      'Canonical tool approval missing guardian binding; rejecting decision',
+      'Canonical request missing guardianPrincipalId; rejecting decision',
+    );
+    return { applied: false, reason: 'identity_mismatch', detail: 'request missing guardianPrincipalId' };
+  }
+
+  if (!actorContext.guardianPrincipalId) {
+    log.warn(
+      {
+        event: 'canonical_decision_missing_actor_principal',
+        requestId,
+        actorChannel: actorContext.channel,
+      },
+      'Actor missing guardianPrincipalId; rejecting decision',
     );
-    return { applied: false, reason: 'identity_mismatch', detail: 'missing guardian binding' };
+    return { applied: false, reason: 'identity_mismatch', detail: 'actor missing guardianPrincipalId' };
   }
 
-  if (
-    request.guardianExternalUserId &&
-    !actorContext.isTrusted &&
-    actorContext.externalUserId !== request.guardianExternalUserId
-  ) {
+  if (actorContext.guardianPrincipalId !== request.guardianPrincipalId) {
     log.warn(
       {
-        event: 'canonical_decision_identity_mismatch',
+        event: 'canonical_decision_principal_mismatch',
         requestId,
-        expectedGuardian: request.guardianExternalUserId,
-        actualActor: actorContext.externalUserId,
+        expectedPrincipal: request.guardianPrincipalId,
+        actualPrincipal: actorContext.guardianPrincipalId,
       },
-      'Actor identity does not match expected guardian',
+      'Actor principal does not match request principal',
     );
-    return { applied: false, reason: 'identity_mismatch' };
+    return { applied: false, reason: 'identity_mismatch', detail: 'principal mismatch' };
   }
 
   // 2d. Check expiry
@@ -416,6 +419,7 @@ export async function applyCanonicalGuardianDecision(
     status: targetStatus,
     answerText: userText,
     decidedByExternalUserId: actorContext.externalUserId,
+    decidedByPrincipalId: actorContext.guardianPrincipalId,
   });
 
   if (!resolved) {

package/src/approvals/guardian-request-resolvers.ts

@@ -39,12 +39,12 @@ const log = getLogger('guardian-request-resolvers');
 
 /** Actor context for the entity making the decision. */
 export interface ActorContext {
-  /** External user ID of the deciding actor (undefined for desktop/trusted). */
+  /** External user ID of the deciding actor (undefined for desktop actors). */
   externalUserId: string | undefined;
   /** Channel the decision arrived on. */
   channel: string;
-  /** Whether the actor is a trusted/desktop context. */
-  isTrusted: boolean;
+  /** Principal ID for authorization — must match the request's guardianPrincipalId. */
+  guardianPrincipalId: string | undefined;
 }
 
 /** The decision being applied. */
@@ -385,7 +385,9 @@ const accessRequestResolver: GuardianRequestResolver = {
       return {
         ok: true,
         applied: true,
-        ...(ctx.actor.isTrusted ? { guardianReplyText: `Access denied for ${requesterLabel}.` } : {}),
+        // Desktop actors (vellum channel) receive inline reply text; channel
+        // actors get replies delivered via the channel delivery context.
+        ...(ctx.actor.channel === 'vellum' ? { guardianReplyText: `Access denied for ${requesterLabel}.` } : {}),
       };
     }
 
@@ -539,7 +541,9 @@ const accessRequestResolver: GuardianRequestResolver = {
     return {
       ok: true,
       applied: true,
-      ...(ctx.actor.isTrusted ? { guardianReplyText: verificationReplyText } : {}),
+      // Desktop actors (vellum channel) receive inline reply text; channel
+      // actors get replies delivered via the channel delivery context.
+      ...(ctx.actor.channel === 'vellum' ? { guardianReplyText: verificationReplyText } : {}),
     };
   },
 };