@vellumai/assistant 0.3.19 → 0.3.21

package/src/runtime/guardian-action-message-composer.ts

@@ -26,11 +26,16 @@ export type GuardianActionMessageScenario =
   | 'guardian_followup_failed'
   | 'guardian_followup_declined_ack'
   | 'guardian_followup_clarification'
+  | 'guardian_pending_disambiguation'
   | 'guardian_expired_disambiguation'
   | 'guardian_followup_disambiguation'
   | 'guardian_stale_answered'
   | 'guardian_stale_expired'
   | 'guardian_stale_followup'
+  | 'guardian_stale_superseded'
+  | 'guardian_superseded_remap'
+  | 'guardian_unknown_code'
+  | 'guardian_auto_matched'
   | 'outbound_message_copy'
   | 'followup_message_sent'
   | 'followup_call_started'
@@ -48,6 +53,10 @@ export interface GuardianActionMessageContext {
   failureReason?: string;
   counterpartyPhone?: string;
   requestCodes?: string[];
+  /** The code the guardian provided that was not recognized. */
+  unknownCode?: string;
+  /** The code of the active request that supersedes the one the guardian targeted. */
+  activeRequestCode?: string;
 }
 
 export interface ComposeGuardianActionMessageOptions {
@@ -181,6 +190,11 @@ export function getGuardianActionFallbackMessage(context: GuardianActionMessageC
     case 'guardian_followup_clarification':
       return "Sorry, I didn't quite catch that. Would you like to call them back, send them a message, or skip it for now?";
 
+    case 'guardian_pending_disambiguation':
+      return listedCodes
+        ? `You have multiple pending guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
+        : 'You have multiple pending guardian questions. Please prefix your reply with the reference code so I know which question you\'re answering.';
+
     case 'guardian_expired_disambiguation':
       return listedCodes
         ? `You have multiple expired guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
@@ -200,6 +214,22 @@ export function getGuardianActionFallbackMessage(context: GuardianActionMessageC
     case 'guardian_stale_followup':
       return 'It looks like this follow-up has already been handled. No further action is needed.';
 
+    case 'guardian_stale_superseded':
+      return 'This request is no longer active. The call has ended and no further action is needed.';
+
+    case 'guardian_unknown_code':
+      return context.unknownCode
+        ? `I don't recognize the code "${context.unknownCode}". Please check the reference code and try again.`
+        : "I don't recognize that reference code. Please check the code and try again.";
+
+    case 'guardian_auto_matched':
+      return 'Got it, routing your answer to the active request.';
+
+    case 'guardian_superseded_remap':
+      return context.questionText
+        ? `Got it! Your answer has been applied to the current active request: "${context.questionText}"`
+        : 'Got it! Your answer has been applied to the current active request on the call.';
+
     case 'outbound_message_copy':
       // This SMS is sent TO the original caller relaying the guardian's answer.
       // When lateAnswerText is available, include it — that's the whole point of message_back.

package/src/runtime/guardian-decision-types.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the guardian decision primitive.
+ *
+ * All decision entrypoints (callback buttons, conversational engine, legacy
+ * parser, requester self-cancel) use these types to route through the
+ * unified `applyGuardianDecision` primitive.
+ */
+
+// ---------------------------------------------------------------------------
+// Guardian decision prompt
+// ---------------------------------------------------------------------------
+
+/** Structured model for prompts shown to guardians. */
+export interface GuardianDecisionPrompt {
+  requestId: string;
+  /** Short human-readable code for the request. */
+  requestCode: string;
+  state: 'pending' | 'followup_awaiting_choice' | 'expired_superseded_with_active_call';
+  questionText: string;
+  toolName: string | null;
+  actions: GuardianDecisionAction[];
+  expiresAt: number;
+  conversationId: string;
+  callSessionId: string | null;
+}
+
+export interface GuardianDecisionAction {
+  /** Canonical action identifier. */
+  action: string;
+  /** Human-readable label for the action. */
+  label: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared decision action constants
+// ---------------------------------------------------------------------------
+
+/** Canonical set of all guardian decision actions with their labels. */
+export const GUARDIAN_DECISION_ACTIONS = {
+  approve_once:   { action: 'approve_once',   label: 'Approve once' },
+  approve_always: { action: 'approve_always', label: 'Approve always' },
+  reject:         { action: 'reject',         label: 'Reject' },
+} as const satisfies Record<string, GuardianDecisionAction>;
+
+/**
+ * Build the set of `GuardianDecisionAction` items appropriate for a prompt,
+ * respecting whether persistent decisions (approve_always) are allowed.
+ *
+ * When `persistentDecisionsAllowed` is `false`, the `approve_always` action
+ * is excluded. When `forGuardianOnBehalf` is `true` (guardian acting on behalf
+ * of a requester), `approve_always` is also excluded since guardians cannot
+ * permanently allowlist tools on behalf of others.
+ */
+export function buildDecisionActions(opts?: {
+  persistentDecisionsAllowed?: boolean;
+  forGuardianOnBehalf?: boolean;
+}): GuardianDecisionAction[] {
+  const showAlways = opts?.persistentDecisionsAllowed !== false && !opts?.forGuardianOnBehalf;
+  return [
+    GUARDIAN_DECISION_ACTIONS.approve_once,
+    ...(showAlways ? [GUARDIAN_DECISION_ACTIONS.approve_always] : []),
+    GUARDIAN_DECISION_ACTIONS.reject,
+  ];
+}
+
+/**
+ * Build the plain-text fallback instruction string that matches the given
+ * set of decision actions. Ensures the text always includes parser-compatible
+ * keywords (yes/always/no) so text-based fallback remains actionable.
+ */
+export function buildPlainTextFallback(
+  promptText: string,
+  actions: GuardianDecisionAction[],
+): string {
+  const hasAlways = actions.some(a => a.action === 'approve_always');
+  return hasAlways
+    ? `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`
+    : `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
+}
+
+// ---------------------------------------------------------------------------
+// Apply decision result
+// ---------------------------------------------------------------------------
+
+export interface ApplyGuardianDecisionResult {
+  applied: boolean;
+  reason?: 'stale' | 'identity_mismatch' | 'invalid_action' | 'not_found' | 'expired';
+  requestId?: string;
+  /** Feedback text when the action was parsed from user text. */
+  userText?: string;
+}

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) {