@vellumai/assistant 0.3.18 → 0.3.20

package/src/runtime/http-server.ts

@@ -6,7 +6,8 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 
 import type { ServerWebSocket } from 'bun';
 
@@ -117,6 +118,10 @@ import {
 } from './routes/conversation-routes.js';
 import { handleDebug } from './routes/debug-routes.js';
 import { handleSubscribeAssistantEvents } from './routes/events-routes.js';
+import {
+  handleGuardianActionDecision,
+  handleGuardianActionsPending,
+} from './routes/guardian-action-routes.js';
 import { handleGetIdentity,handleHealth } from './routes/identity-routes.js';
 import {
   handleBlockMember,
@@ -237,11 +242,24 @@ export class RuntimeHttpServer {
     this.pairingBroadcast = fn;
   }
 
+  /** Read the feature-flag client token from disk so it can be included in pairing approval responses. */
+  private readFeatureFlagToken(): string | undefined {
+    try {
+      const baseDir = process.env.BASE_DATA_DIR?.trim() || homedir();
+      const tokenPath = join(baseDir, '.vellum', 'feature-flag-token');
+      const token = readFileSync(tokenPath, 'utf-8').trim();
+      return token || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   private get pairingContext(): PairingHandlerContext {
     const ipcBroadcast = this.pairingBroadcast;
     return {
       pairingStore: this.pairingStore,
       bearerToken: this.bearerToken,
+      featureFlagToken: this.readFeatureFlagToken(),
       pairingBroadcast: ipcBroadcast
         ? (msg) => {
             // Broadcast to IPC socket clients (local Unix socket)
@@ -690,6 +708,10 @@ export class RuntimeHttpServer {
       if (endpoint === 'trust-rules' && req.method === 'POST') return await handleTrustRule(req);
       if (endpoint === 'pending-interactions' && req.method === 'GET') return handleListPendingInteractions(url);
 
+      // Guardian action endpoints — deterministic button-based decisions
+      if (endpoint === 'guardian-actions/pending' && req.method === 'GET') return handleGuardianActionsPending(req);
+      if (endpoint === 'guardian-actions/decision' && req.method === 'POST') return await handleGuardianActionDecision(req);
+
       // Contacts
       if (endpoint === 'contacts' && req.method === 'GET') return handleListContacts(url);
       if (endpoint === 'contacts/merge' && req.method === 'POST') return await handleMergeContacts(req);

package/src/runtime/ingress-service.ts

@@ -22,6 +22,10 @@ import {
   revokeMember,
   upsertMember,
 } from '../memory/ingress-member-store.js';
+import {
+  type InviteRedemptionOutcome,
+  redeemInvite as redeemInviteTyped,
+} from './invite-redemption-service.js';
 
 // ---------------------------------------------------------------------------
 // Response shapes — used by both HTTP routes and IPC handlers
@@ -163,6 +167,24 @@ export function redeemIngressInvite(params: {
   return { ok: true, data: inviteToResponse(result.invite) };
 }
 
+// ---------------------------------------------------------------------------
+// Typed invite redemption — preferred entry point for new callers
+// ---------------------------------------------------------------------------
+
+export { type InviteRedemptionOutcome } from './invite-redemption-service.js';
+
+export function redeemIngressInviteTyped(params: {
+  rawToken: string;
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  assistantId?: string;
+}): InviteRedemptionOutcome {
+  return redeemInviteTyped(params);
+}
+
 // ---------------------------------------------------------------------------
 // Member operations
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,181 @@
+/**
+ * Typed invite redemption engine.
+ *
+ * Wraps the low-level invite store primitives with channel-scoped enforcement
+ * and a discriminated-union outcome type so callers can handle every case
+ * deterministically. The raw token is accepted as input but is never logged,
+ * persisted, or returned in the outcome.
+ */
+
+import { getSqlite } from '../memory/db.js';
+import { findByTokenHash, hashToken, markInviteExpired, recordInviteUse,redeemInvite as storeRedeemInvite } from '../memory/ingress-invite-store.js';
+import { findMember, upsertMember } from '../memory/ingress-member-store.js';
+
+// ---------------------------------------------------------------------------
+// Outcome type
+// ---------------------------------------------------------------------------
+
+export type InviteRedemptionOutcome =
+  | { ok: true; type: 'redeemed'; memberId: string; inviteId: string }
+  | { ok: true; type: 'already_member'; memberId: string }
+  | { ok: false; reason: 'invalid_token' | 'expired' | 'revoked' | 'max_uses_reached' | 'channel_mismatch' | 'missing_identity' };
+
+// ---------------------------------------------------------------------------
+// Error-string to typed-reason mapping
+// ---------------------------------------------------------------------------
+
+const STORE_ERROR_TO_REASON: Record<string, InviteRedemptionOutcome & { ok: false } | undefined> = {
+  invite_not_found: { ok: false, reason: 'invalid_token' },
+  invite_expired: { ok: false, reason: 'expired' },
+  invite_revoked: { ok: false, reason: 'revoked' },
+  invite_redeemed: { ok: false, reason: 'max_uses_reached' },
+  invite_max_uses_reached: { ok: false, reason: 'max_uses_reached' },
+  invite_channel_mismatch: { ok: false, reason: 'channel_mismatch' },
+};
+
+// ---------------------------------------------------------------------------
+// redeemInvite
+// ---------------------------------------------------------------------------
+
+export function redeemInvite(params: {
+  rawToken: string;
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  assistantId?: string;
+}): InviteRedemptionOutcome {
+  const { rawToken, sourceChannel, externalUserId, externalChatId, displayName, username, assistantId } = params;
+
+  if (!externalUserId && !externalChatId) {
+    return { ok: false, reason: 'missing_identity' };
+  }
+
+  // Validate the invite token before any membership checks to prevent
+  // membership-status probing with arbitrary tokens.
+  const tokenHash = hashToken(rawToken);
+  const invite = findByTokenHash(tokenHash);
+
+  if (!invite) {
+    return { ok: false, reason: 'invalid_token' };
+  }
+
+  if (invite.status !== 'active') {
+    const mapped = STORE_ERROR_TO_REASON[`invite_${invite.status}`];
+    if (mapped) return mapped;
+    return { ok: false, reason: 'invalid_token' };
+  }
+
+  if (invite.expiresAt <= Date.now()) {
+    markInviteExpired(invite.id);
+    return { ok: false, reason: 'expired' };
+  }
+
+  if (invite.useCount >= invite.maxUses) {
+    return { ok: false, reason: 'max_uses_reached' };
+  }
+
+  // Enforce channel match: the token must belong to the channel the caller
+  // is redeeming from.
+  if (sourceChannel !== invite.sourceChannel) {
+    return { ok: false, reason: 'channel_mismatch' };
+  }
+
+  // Token is valid — now safe to check existing membership without leaking
+  // membership status to callers with bogus tokens.
+  const existingMember = findMember({
+    assistantId: assistantId ?? invite.assistantId,
+    sourceChannel,
+    externalUserId,
+    externalChatId,
+  });
+
+  if (existingMember && existingMember.status === 'active') {
+    return { ok: true, type: 'already_member', memberId: existingMember.id };
+  }
+
+  // Blocked members cannot bypass the guardian's explicit block via invite
+  // links. Return the same generic failure as an invalid token to avoid
+  // leaking membership status to the caller.
+  if (existingMember && existingMember.status === 'blocked') {
+    return { ok: false, reason: 'invalid_token' };
+  }
+
+  // Inactive member reactivation: when the user already has a member record
+  // in a non-active state (revoked/pending), reactivate it via upsertMember
+  // and consume an invite use atomically. Falling through to storeRedeemInvite
+  // would try to INSERT a new member row, hitting the unique-key constraint
+  // on the members table.
+  if (existingMember) {
+    // 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');
+
+    let reactivated: ReturnType<typeof upsertMember> | undefined;
+    try {
+      getSqlite().transaction(() => {
+        reactivated = upsertMember({
+          assistantId: assistantId ?? invite.assistantId,
+          sourceChannel,
+          externalUserId,
+          externalChatId,
+          displayName,
+          username,
+          status: 'active',
+          policy: 'allow',
+          inviteId: invite.id,
+        });
+
+        const recorded = recordInviteUse({
+          inviteId: invite.id,
+          externalUserId,
+          externalChatId,
+        });
+
+        // If the invite was revoked/expired between pre-validation and this
+        // write, recordInviteUse returns false — throw to roll back the
+        // member reactivation so the DB stays consistent.
+        if (!recorded) throw STALE_INVITE;
+      }).immediate();
+    } catch (err) {
+      if (err === STALE_INVITE) {
+        return { ok: false, reason: 'invalid_token' };
+      }
+      throw err;
+    }
+
+    return {
+      ok: true,
+      type: 'redeemed',
+      memberId: reactivated!.id,
+      inviteId: invite.id,
+    };
+  }
+
+  // Delegate to the store-level redeem which handles token lookup, expiry,
+  // use-count, and transactional member creation. Channel enforcement is
+  // applied by passing sourceChannel so the store checks it.
+  const result = storeRedeemInvite({
+    rawToken,
+    sourceChannel,
+    externalUserId,
+    externalChatId,
+    displayName,
+    username,
+  });
+
+  if ('error' in result) {
+    const mapped = STORE_ERROR_TO_REASON[result.error];
+    if (mapped) return mapped;
+    // Fallback for any unrecognized store error
+    return { ok: false, reason: 'invalid_token' };
+  }
+
+  return {
+    ok: true,
+    type: 'redeemed',
+    memberId: result.member.id,
+    inviteId: result.invite.id,
+  };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Deterministic reply templates for invite token redemption outcomes.
+ *
+ * These messages are returned directly to the user without passing through
+ * the LLM pipeline, ensuring consistent and predictable responses for
+ * every invite redemption outcome.
+ */
+
+import type { InviteRedemptionOutcome } from './invite-redemption-service.js';
+
+// ---------------------------------------------------------------------------
+// Template strings
+// ---------------------------------------------------------------------------
+
+export const INVITE_REPLY_TEMPLATES = {
+  redeemed: "Welcome! You've been granted access via invite link.",
+  already_member: 'You already have access.',
+  invalid_token: 'This invite link is no longer valid.',
+  expired: 'This invite link is no longer valid.',
+  revoked: 'This invite link is no longer valid.',
+  max_uses_reached: 'This invite link is no longer valid.',
+  channel_mismatch: 'This invite link is not valid for this channel.',
+  missing_identity: 'Unable to process this invite. Please contact the person who shared it.',
+  generic_failure: 'Unable to process this invite. Please contact the person who shared it.',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Outcome-to-reply resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an `InviteRedemptionOutcome` to a deterministic reply string.
+ */
+export function getInviteRedemptionReply(outcome: InviteRedemptionOutcome): string {
+  if (outcome.ok) {
+    return INVITE_REPLY_TEMPLATES[outcome.type];
+  }
+  return INVITE_REPLY_TEMPLATES[outcome.reason] ?? INVITE_REPLY_TEMPLATES.generic_failure;
+}

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

@@ -179,7 +179,7 @@ export async function handleCancelCall(req: Request, callSessionId: string): Pro
  * Body: { answer: string }
  */
 export async function handleAnswerCall(req: Request, callSessionId: string): Promise<Response> {
-  let body: { answer?: string };
+  let body: { answer?: string; pendingQuestionId?: string };
   try {
     body = await req.json() as typeof body;
   } catch {
@@ -193,6 +193,7 @@ export async function handleAnswerCall(req: Request, callSessionId: string): Pro
   const result = await answerCall({
     callSessionId,
     answer: body.answer ?? '',
+    pendingQuestionId: typeof body.pendingQuestionId === 'string' ? body.pendingQuestionId : undefined,
   });
 
   if (!result.ok) {

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

@@ -0,0 +1,206 @@
+/**
+ * Route handlers for deterministic guardian action endpoints.
+ *
+ * These endpoints let desktop clients fetch pending guardian prompts and
+ * submit button decisions without relying on text parsing.
+ */
+import { applyGuardianDecision } from '../../approvals/guardian-decision-primitive.js';
+import {
+  getPendingApprovalForRequest,
+  listPendingApprovalRequests,
+} from '../../memory/channel-guardian-store.js';
+import type { ApprovalAction } from '../channel-approval-types.js';
+import { handleChannelDecision } from '../channel-approvals.js';
+import type { GuardianDecisionPrompt } from '../guardian-decision-types.js';
+import { buildDecisionActions } from '../guardian-decision-types.js';
+import { httpError } from '../http-errors.js';
+import * as pendingInteractions from '../pending-interactions.js';
+import { handleAccessRequestDecision } from './access-request-decision.js';
+
+// ---------------------------------------------------------------------------
+// GET /v1/guardian-actions/pending?conversationId=...
+// ---------------------------------------------------------------------------
+
+/**
+ * List pending guardian decision prompts for a conversation.
+ *
+ * Returns guardian approval requests (from the channel guardian store) that
+ * are still pending, mapped to the GuardianDecisionPrompt shape so clients
+ * can render structured button UIs.
+ */
+export function handleGuardianActionsPending(req: Request): Response {
+  const url = new URL(req.url);
+  const conversationId = url.searchParams.get('conversationId');
+
+  if (!conversationId) {
+    return httpError('BAD_REQUEST', 'conversationId query parameter is required', 400);
+  }
+
+  const prompts = listGuardianDecisionPrompts({ conversationId });
+  return Response.json({ conversationId, prompts });
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/guardian-actions/decision
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit a guardian action decision.
+ *
+ * Looks up the guardian approval by requestId and applies the decision
+ * through the unified guardian decision primitive.
+ */
+export async function handleGuardianActionDecision(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    requestId?: string;
+    action?: string;
+    conversationId?: string;
+  };
+
+  const { requestId, action, conversationId } = body;
+
+  if (!requestId || typeof requestId !== 'string') {
+    return httpError('BAD_REQUEST', 'requestId is required', 400);
+  }
+
+  if (!action || typeof action !== 'string') {
+    return httpError('BAD_REQUEST', 'action is required', 400);
+  }
+
+  const VALID_ACTIONS = new Set<string>(['approve_once', 'approve_always', 'reject']);
+  if (!VALID_ACTIONS.has(action)) {
+    return httpError('BAD_REQUEST', `Invalid action: ${action}. Must be one of: approve_once, approve_always, reject`, 400);
+  }
+
+  // Try the channel guardian approval store first (tool approval prompts)
+  const approval = getPendingApprovalForRequest(requestId);
+  if (approval) {
+    // Enforce conversationId scoping: reject decisions that target the wrong conversation.
+    if (conversationId && conversationId !== approval.conversationId) {
+      return httpError('BAD_REQUEST', 'conversationId does not match the approval', 400);
+    }
+
+    // Access request approvals need a separate decision path — they don't have
+    // pending interactions and use verification sessions instead.
+    if (approval.toolName === 'ingress_access_request') {
+      const mappedAction = action === 'reject' ? 'deny' as const : 'approve' as const;
+      // Use 'desktop' as the actor identity because this endpoint is
+      // unauthenticated — we cannot verify the caller is the assigned
+      // guardian, so we record a generic desktop origin instead of
+      // falsely attributing the decision to guardianExternalUserId.
+      const decisionResult = handleAccessRequestDecision(
+        approval,
+        mappedAction,
+        'desktop',
+      );
+      return Response.json({
+        applied: decisionResult.type !== 'stale',
+        requestId,
+        reason: decisionResult.type === 'stale' ? 'stale' : undefined,
+        accessRequestResult: decisionResult,
+      });
+    }
+
+    // Note: actorExternalUserId is left undefined because the desktop endpoint
+    // does not authenticate caller identity. This means scoped grant minting is
+    // skipped for button-based decisions — an acceptable trade-off to avoid
+    // falsifying audit records with an unverified guardian identity.
+    const result = applyGuardianDecision({
+      approval,
+      decision: { action: action as 'approve_once' | 'approve_always' | 'reject', source: 'plain_text', requestId },
+      actorExternalUserId: undefined,
+      actorChannel: 'vellum',
+    });
+    return Response.json({ ...result, requestId: result.requestId ?? requestId });
+  }
+
+  // Fall back to the pending interactions tracker (direct confirmation requests).
+  // Route through handleChannelDecision so approve_always properly persists trust rules.
+  const interaction = pendingInteractions.get(requestId);
+  if (interaction) {
+    // Enforce conversationId scoping for interactions too.
+    if (conversationId && conversationId !== interaction.conversationId) {
+      return httpError('BAD_REQUEST', 'conversationId does not match the interaction', 400);
+    }
+
+    const result = handleChannelDecision(
+      interaction.conversationId,
+      { action: action as ApprovalAction, source: 'plain_text', requestId },
+    );
+    return Response.json({ ...result, requestId: result.requestId ?? requestId });
+  }
+
+  return httpError('NOT_FOUND', 'No pending guardian action found for this requestId', 404);
+}
+
+// ---------------------------------------------------------------------------
+// Shared helper: list guardian decision prompts
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a list of GuardianDecisionPrompt objects for the given conversation.
+ *
+ * Aggregates pending guardian approval requests from the channel guardian
+ * store and pending confirmation interactions from the pending-interactions
+ * tracker, exposing them in a uniform shape that clients can render as
+ * structured button UIs.
+ */
+export function listGuardianDecisionPrompts(params: {
+  conversationId: string;
+}): GuardianDecisionPrompt[] {
+  const { conversationId } = params;
+  const prompts: GuardianDecisionPrompt[] = [];
+
+  // 1. Channel guardian approval requests (tool approvals routed to guardians)
+  const approvalRequests = listPendingApprovalRequests({
+    conversationId,
+    status: 'pending',
+  }).filter(a => a.expiresAt > Date.now() && a.requestId != null);
+
+  for (const approval of approvalRequests) {
+    const reqId = approval.requestId!;
+    prompts.push({
+      requestId: reqId,
+      requestCode: reqId.slice(0, 6).toUpperCase(),
+      state: 'pending',
+      questionText: approval.reason ?? `Approve tool: ${approval.toolName ?? 'unknown'}`,
+      toolName: approval.toolName ?? null,
+      actions: buildDecisionActions({ forGuardianOnBehalf: true }),
+      expiresAt: approval.expiresAt,
+      conversationId: approval.conversationId,
+      callSessionId: null,
+    });
+  }
+
+  // 2. Guardian action requests (voice call guardian questions) are intentionally
+  // excluded here — resolving them requires the answerCall + resolveGuardianActionRequest
+  // flow which is handled by the conversational session-process path, not by the
+  // deterministic button decision endpoint.
+  // TODO: Surface voice guardian-action requests as read-only informational prompts
+  // so desktop clients can see them even though they can't be resolved via buttons.
+
+  // 3. Pending confirmation interactions (direct tool approval prompts)
+  const interactions = pendingInteractions.getByConversation(conversationId);
+  for (const interaction of interactions) {
+    if (interaction.kind !== 'confirmation' || !interaction.confirmationDetails) continue;
+    // Skip if already covered by a channel guardian approval above
+    if (prompts.some(p => p.requestId === interaction.requestId)) continue;
+
+    const details = interaction.confirmationDetails;
+    prompts.push({
+      requestId: interaction.requestId,
+      requestCode: interaction.requestId.slice(0, 6).toUpperCase(),
+      state: 'pending',
+      questionText: `Approve tool: ${details.toolName}`,
+      toolName: details.toolName,
+      actions: buildDecisionActions({
+        persistentDecisionsAllowed: details.persistentDecisionsAllowed,
+      }),
+      expiresAt: Date.now() + 300_000,
+      conversationId,
+      callSessionId: null,
+    });
+  }
+
+  return prompts;
+}