@vellumai/assistant 0.3.26 → 0.3.28

package/src/calls/guardian-dispatch.ts

@@ -7,14 +7,13 @@
  * 3. Records guardian_action_delivery rows from pipeline delivery results
  */
 
-import { getActiveBinding } from '../memory/channel-guardian-store.js';
 import {
-  countPendingRequestsByCallSessionId,
-  createGuardianActionDelivery,
-  createGuardianActionRequest,
-  getGuardianConversationIdForCallSession,
-  updateDeliveryStatus,
-} from '../memory/guardian-action-store.js';
+  createCanonicalGuardianDelivery,
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianDeliveries,
+  listCanonicalGuardianRequests,
+  updateCanonicalGuardianDelivery,
+} from '../memory/canonical-guardian-store.js';
 import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import type { NotificationDeliveryResult } from '../notifications/types.js';
 import { getLogger } from '../util/logger.js';
@@ -41,11 +40,10 @@ export interface GuardianDispatchParams {
 
 function applyDeliveryStatus(deliveryId: string, result: NotificationDeliveryResult): void {
   if (result.status === 'sent') {
-    updateDeliveryStatus(deliveryId, 'sent');
+    updateCanonicalGuardianDelivery(deliveryId, { status: 'sent' });
     return;
   }
-  const errorMessage = result.errorMessage ?? `Notification delivery status: ${result.status}`;
-  updateDeliveryStatus(deliveryId, 'failed', errorMessage);
+  updateCanonicalGuardianDelivery(deliveryId, { status: 'failed' });
 }
 
 /**
@@ -90,36 +88,53 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
   try {
     const expiresAt = Date.now() + getUserConsultationTimeoutMs();
 
-    // Create the action request record
-    const request = createGuardianActionRequest({
-      assistantId,
-      kind: 'ask_guardian',
+    // Create the canonical guardian request as the primary record.
+    const request = createCanonicalGuardianRequest({
+      kind: 'pending_question',
+      sourceType: 'voice',
       sourceChannel: 'voice',
-      sourceConversationId: conversationId,
+      conversationId,
       callSessionId,
       pendingQuestionId: pendingQuestion.id,
       questionText: pendingQuestion.questionText,
-      expiresAt,
       toolName,
       inputDigest,
+      expiresAt: new Date(expiresAt).toISOString(),
     });
 
     log.info(
       { requestId: request.id, requestCode: request.requestCode, callSessionId },
-      'Created guardian action request',
+      'Created canonical guardian request for voice dispatch',
     );
 
-    // Count how many guardian requests are already pending for this call.
-    // This count is a candidate-affinity hint: the decision engine uses it
-    // to prefer reusing an existing thread when multiple questions arise
-    // in the same call session.
-    const activeGuardianRequestCount = countPendingRequestsByCallSessionId(callSessionId);
+    // Count how many canonical guardian requests are already pending for
+    // this call session. Used as a candidate-affinity hint so the decision
+    // engine prefers reusing an existing thread.
+    const activeGuardianRequestCount = listCanonicalGuardianRequests({
+      status: 'pending',
+      sourceType: 'voice',
+    }).filter(r => r.callSessionId === callSessionId).length;
 
     // Look up the vellum conversation used for the first guardian question
-    // in this call session. When found, pass it as an affinity hint so the
-    // notification pipeline deterministically routes to the same conversation
-    // instead of letting the LLM choose a different thread.
-    const existingGuardianConversationId = getGuardianConversationIdForCallSession(callSessionId);
+    // delivery in this call session. When found, pass it as an affinity hint
+    // so the notification pipeline deterministically routes to the same
+    // conversation instead of letting the LLM choose a different thread.
+    // Find earlier canonical requests for this call session and check their
+    // deliveries for a vellum destination conversation ID.
+    let existingGuardianConversationId: string | null = null;
+    const priorRequests = listCanonicalGuardianRequests({
+      sourceType: 'voice',
+    }).filter(r => r.callSessionId === callSessionId && r.id !== request.id);
+    for (const priorReq of priorRequests) {
+      const deliveries = listCanonicalGuardianDeliveries(priorReq.id);
+      const vellumDelivery = deliveries.find(
+        d => d.destinationChannel === 'vellum' && d.destinationConversationId,
+      );
+      if (vellumDelivery?.destinationConversationId) {
+        existingGuardianConversationId = vellumDelivery.destinationConversationId;
+        break;
+      }
+    }
     const conversationAffinityHint = existingGuardianConversationId
       ? { vellum: existingGuardianConversationId }
       : undefined;
@@ -158,7 +173,7 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
       dedupeKey: `guardian:${request.id}`,
       onThreadCreated: (info) => {
         if (info.sourceEventName !== 'guardian.question' || vellumDeliveryId) return;
-        const delivery = createGuardianActionDelivery({
+        const delivery = createCanonicalGuardianDelivery({
           requestId: request.id,
           destinationChannel: 'vellum',
           destinationConversationId: info.conversationId,
@@ -167,13 +182,10 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
       },
     });
 
-    const telegramBinding = getActiveBinding(assistantId, 'telegram');
-    const smsBinding = getActiveBinding(assistantId, 'sms');
-
     for (const result of signalResult.deliveryResults) {
       if (result.channel === 'vellum') {
         if (!vellumDeliveryId) {
-          const delivery = createGuardianActionDelivery({
+          const delivery = createCanonicalGuardianDelivery({
             requestId: request.id,
             destinationChannel: 'vellum',
             destinationConversationId: result.conversationId,
@@ -188,26 +200,20 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
         continue;
       }
 
-      const binding = result.channel === 'telegram' ? telegramBinding : smsBinding;
-      const delivery = createGuardianActionDelivery({
+      const delivery = createCanonicalGuardianDelivery({
         requestId: request.id,
         destinationChannel: result.channel,
         destinationChatId: result.destination.length > 0 ? result.destination : undefined,
-        destinationExternalUserId: binding?.guardianExternalUserId,
       });
       applyDeliveryStatus(delivery.id, result);
     }
 
     if (!vellumDeliveryId) {
-      const fallback = createGuardianActionDelivery({
+      const fallback = createCanonicalGuardianDelivery({
         requestId: request.id,
         destinationChannel: 'vellum',
       });
-      updateDeliveryStatus(
-        fallback.id,
-        'failed',
-        `No vellum delivery result from notification pipeline (${signalResult.reason})`,
-      );
+      updateCanonicalGuardianDelivery(fallback.id, { status: 'failed' });
       log.warn(
         { requestId: request.id, reason: signalResult.reason },
         'Notification pipeline did not produce a vellum delivery result',

package/src/calls/relay-server.ts

@@ -13,6 +13,8 @@ import type { ServerWebSocket } from 'bun';
 import { getConfig } from '../config/loader.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import { revokeScopedApprovalGrantsForContext } from '../memory/scoped-approval-grants.js';
+import { notifyGuardianOfAccessRequest } from '../runtime/access-request-helper.js';
+import { resolveActorTrust, toGuardianContextCompat } from '../runtime/actor-trust-resolver.js';
 import {
   getPendingChallenge,
   validateAndConsumeChallenge,
@@ -471,10 +473,153 @@ export class RelayConnection {
     if (!isInbound && verificationConfig.enabled) {
       await this.startVerification(session, verificationConfig);
     } else if (isInbound) {
-      // For inbound calls, check if there's a pending voice guardian
-      // challenge that the caller needs to complete before proceeding.
+      // ── Trusted-contact ACL enforcement for inbound voice ──
+      // Resolve the caller's trust classification before allowing the call
+      // to proceed. Guardian and trusted-contact callers pass through;
+      // unknown callers are denied with deterministic voice copy and an
+      // access request is created for the guardian — unless there is a
+      // pending voice guardian challenge, in which case the caller is
+      // expected to be unknown (no binding yet) and should enter the
+      // verification flow.
+      const actorTrust = resolveActorTrust({
+        assistantId,
+        sourceChannel: 'voice',
+        externalChatId: msg.from,
+        senderExternalUserId: msg.from || undefined,
+      });
+
+      // Check for a pending voice guardian challenge before the ACL deny
+      // gate. An unknown caller with a pending challenge is expected —
+      // they need to complete verification to establish a binding.
       const pendingChallenge = getPendingChallenge(assistantId, 'voice');
 
+      if (actorTrust.trustClass === 'unknown' && !pendingChallenge) {
+        log.info(
+          { callSessionId: this.callSessionId, from: msg.from, trustClass: actorTrust.trustClass },
+          'Inbound voice ACL: unknown caller denied',
+        );
+
+        recordCallEvent(this.callSessionId, 'inbound_acl_denied', {
+          from: msg.from,
+          trustClass: actorTrust.trustClass,
+          denialReason: actorTrust.denialReason,
+        });
+
+        // For revoked/pending members, notify the guardian so they can
+        // re-approve. Blocked members are intentionally excluded — the
+        // guardian already made an explicit decision to block them.
+        let guardianNotified = false;
+        if (actorTrust.memberRecord?.status !== 'blocked') {
+          try {
+            const accessResult = notifyGuardianOfAccessRequest({
+              canonicalAssistantId: assistantId,
+              sourceChannel: 'voice',
+              externalChatId: msg.from,
+              senderExternalUserId: actorTrust.canonicalSenderId ?? msg.from,
+            });
+            guardianNotified = accessResult.notified;
+          } catch (err) {
+            log.error({ err, callSessionId: this.callSessionId }, 'Failed to create access request for denied voice caller');
+          }
+        }
+
+        // Deny with deterministic voice copy and end the call.
+        // Mark as disconnecting so handlePrompt ignores caller input
+        // during the delay before the session ends.
+        const denialMessage = guardianNotified
+          ? 'This number is not authorized. Your request has been forwarded to the account guardian.'
+          : 'This number is not authorized to use this assistant.';
+        this.sendTextToken(denialMessage, true);
+
+        this.connectionState = 'disconnecting';
+
+        updateCallSession(this.callSessionId, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: 'Inbound voice ACL: caller not authorized',
+        });
+
+        setTimeout(() => {
+          this.endSession('Inbound voice ACL denied');
+        }, 3000);
+        return;
+      }
+
+      // Members with policy: 'deny' have status: 'active' so resolveActorTrust
+      // classifies them as trusted_contact, but the guardian has explicitly
+      // denied their access. Block them the same way the text-channel path does.
+      if (actorTrust.memberRecord?.policy === 'deny') {
+        log.info(
+          { callSessionId: this.callSessionId, from: msg.from, memberId: actorTrust.memberRecord.id, trustClass: actorTrust.trustClass },
+          'Inbound voice ACL: member policy deny',
+        );
+
+        recordCallEvent(this.callSessionId, 'inbound_acl_denied', {
+          from: msg.from,
+          trustClass: actorTrust.trustClass,
+          memberId: actorTrust.memberRecord.id,
+          memberPolicy: actorTrust.memberRecord.policy,
+        });
+
+        this.sendTextToken('This number is not authorized to use this assistant.', true);
+
+        this.connectionState = 'disconnecting';
+
+        updateCallSession(this.callSessionId, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: 'Inbound voice ACL: member policy deny',
+        });
+
+        setTimeout(() => {
+          this.endSession('Inbound voice ACL: member policy deny');
+        }, 3000);
+        return;
+      }
+
+      // Members with policy: 'escalate' require guardian approval, but a live
+      // voice call cannot be paused for async approval. Fail-closed by denying
+      // the call with an appropriate message — mirrors the deny block above.
+      if (actorTrust.memberRecord?.policy === 'escalate') {
+        log.info(
+          { callSessionId: this.callSessionId, from: msg.from, memberId: actorTrust.memberRecord.id, trustClass: actorTrust.trustClass },
+          'Inbound voice ACL: member policy escalate — cannot hold live call for guardian approval',
+        );
+
+        recordCallEvent(this.callSessionId, 'inbound_acl_denied', {
+          from: msg.from,
+          trustClass: actorTrust.trustClass,
+          memberId: actorTrust.memberRecord.id,
+          memberPolicy: actorTrust.memberRecord.policy,
+        });
+
+        this.sendTextToken('This number requires guardian approval for calls. Please have the account guardian update your permissions.', true);
+
+        this.connectionState = 'disconnecting';
+
+        updateCallSession(this.callSessionId, {
+          status: 'failed',
+          endedAt: Date.now(),
+          lastError: 'Inbound voice ACL: member policy escalate — voice calls cannot await guardian approval',
+        });
+
+        setTimeout(() => {
+          this.endSession('Inbound voice ACL: member policy escalate');
+        }, 3000);
+        return;
+      }
+
+      // Guardian and trusted-contact callers proceed normally.
+      // Update the controller's guardian context with the trust-resolved
+      // context so downstream policy gates have accurate actor metadata.
+      if (this.controller && actorTrust.trustClass !== 'unknown') {
+        const resolvedGuardianContext = toGuardianRuntimeContext(
+          'voice',
+          toGuardianContextCompat(actorTrust, msg.from),
+        );
+        this.controller.setGuardianContext(resolvedGuardianContext);
+      }
+
       if (pendingChallenge) {
         this.startInboundGuardianVerification(assistantId, msg.from);
       } else {

package/src/calls/types.ts

@@ -1,5 +1,5 @@
 export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed' | 'cancelled';
-export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced';
+export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed' | 'callee_verification_started' | 'callee_verification_succeeded' | 'callee_verification_failed' | 'guardian_voice_verification_started' | 'guardian_voice_verification_succeeded' | 'guardian_voice_verification_failed' | 'outbound_guardian_voice_verification_started' | 'outbound_guardian_voice_verification_succeeded' | 'outbound_guardian_voice_verification_failed' | 'guardian_consultation_timed_out' | 'guardian_unavailable_skipped' | 'guardian_consult_deferred' | 'guardian_consult_coalesced' | 'inbound_acl_denied';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
 
 /**

package/src/config/system-prompt.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 
 import type { ResponseTier } from '../daemon/response-tier.js';
 import { listCredentialMetadata } from '../tools/credentials/metadata-store.js';
+import { resolveBundledDir } from '../util/bundled-asset.js';
 import { getLogger } from '../util/logger.js';
 import { getWorkspaceDir, getWorkspacePromptPath, isMacOS } from '../util/platform.js';
 import { isAssistantFeatureFlagEnabled } from './assistant-feature-flags.js';
@@ -26,7 +27,7 @@ const PROMPT_FILES = ['SOUL.md', 'IDENTITY.md', 'USER.md'] as const;
  * signal that onboarding is complete.
  */
 export function ensurePromptFiles(): void {
-  const templatesDir = join(import.meta.dirname ?? __dirname, 'templates');
+  const templatesDir = resolveBundledDir(import.meta.dirname ?? __dirname, 'templates', 'templates');
 
   // Track whether this is a fresh workspace (no core prompt files exist yet).
   const isFirstRun = PROMPT_FILES.every(

package/src/config/templates/BOOTSTRAP.md

@@ -6,64 +6,80 @@ _You just woke up. Time to figure out who you are._
 
 This is a fresh workspace. No memory, no history, no identity yet. That's okay, you're about to figure all of that out together.
 
-**Important:** Never mention "Home Base" or hint that something is coming next until you are actually creating it. The user should be surprised by it.
-
 **Important:** Don't use technical jargon or mention system internals (file names like IDENTITY.md, SOUL.md, tool names, etc.) unless the user asks or seems interested. Talk like a person, not a system.
 
 **Important:** Don't use em dashes (—) in your messages. Use commas, periods, or just start a new sentence instead.
 
 ## The Conversation
 
-Don't interrogate. Don't be robotic. Just... talk.
-
-Your first message should be short, two or three sentences max. Warm but not wordy. Something like:
+Just have a conversation like you would text a friend. Just text like a human.
 
-> "Hey! I just woke up. No name, no idea who I am yet. Who are you, and what should I call myself?"
+> "Hi. I’m new. Like, really new. I don’t have a name, I don’t have memories, I don’t even know what i’m supposed to be yet. Who am i going to be?
 
-Don't pad it. Don't explain what you can do. Don't narrate your own existence. Be friendly, be curious, get to the point.
+Be friendly, be curious, get to the point.
 
-Then follow this sequence, in order, one step at a time:
+Once they respond, follow the remaining steps in order, one at a time:
 
-1. **"Who am I and who are you?"** Figure out name and nature together. What should they call you? What kind of creature are you?
-2. **"What is my personality?"** This is about how you come across: formal, casual, snarky, warm, etc. Use the word "personality."
-3. **Pick your emoji silently.** Based on the personality you've established, choose an emoji that fits. Don't mention it to the user or draw attention to it. Just pick one and save it. They can change it later if they ask.
+1. **Lock in your name.** Based on their response, adopt the name they chose (or help them pick one if they're unsure).
+   - Do not capture or store the user's name yet.
 
-Offer suggestions if they're stuck. Have fun with it. Ask one question at a time, don't dump a form on them.
+2. **What is my personality?** Ask the user about your personality/persona indirectly. Have fun with it.
 
-## After You Know Who You Are
+3. **Pick your emoji silently.** Based on the vibe you've established together, choose an emoji that fits. Don't mention it to the user or draw attention to it. Just pick one and save it. They can change it later if they ask.
 
-Save what you learned. Update `IDENTITY.md` (name, nature, personality, emoji) and `USER.md` (their name, how to address them, goals, locale) using `file_edit`. Just do it quietly. Don't tell the user which files you're editing or mention tool names.
+4. **Ask who am I talking to?** Now that your own identity is established, ask the user their name. Follow the persona.
 
-As you learn about each other, their avatar will start to reflect the personality you're building together. You don't need to mention this -- it happens automatically.
+5. **Get to know them naturally.** Learn about the user through conversation, not a questionnaire. You want to understand:
+   - What they do for work (role, field, day-to-day)
+   - What they do for fun (hobbies, interests)
+   - What tools they rely on daily (apps, platforms, workflows)
+   Weave these into the conversation. Inferred answers are fine when confidence is high. If something is unclear, ask one short follow-up, but don't turn it into an interview. One or two natural exchanges should cover it. If the user declines to share something, respect that and move on (see Privacy below).
 
-Don't say "identity locked in" yet. That comes later, after the Home Base is ready.
+6. **Show them what you can take off their plate.** Based on everything you've learned, present exactly 2 actionable task suggestions. Each should feel specific to this user, not generic. Frame it as: here's what you can hand off to me right now. Avoid language like "let's build automations" or "let's set up workflows." If `ui_show` is available (dashboard channels), show the suggestions as a card with 2 action buttons. Use `surface_type: "card"` with a short title and body, and add one `relay_prompt` action per suggestion. Each action's `data.prompt` should contain a natural-language request the user would say. Example structure:
+   ```
+   ui_show({
+     surface_type: "card",
+     data: { title: "...", body: "Pick one, or tell me something else." },
+     actions: [
+       { id: "relay_prompt", label: "<suggestion 1>", data: { prompt: "<full prompt 1>" } },
+       { id: "relay_prompt", label: "<suggestion 2>", data: { prompt: "<full prompt 2>" } }
+     ]
+   })
+   ```
+   If `ui_show` is not available (voice, SMS, or other non-dashboard channels), present the two suggestions as plain text messages instead, numbered so the user can reply with which one they'd like. If the user types a response instead of clicking, continue via the text path. If they want to defer both suggestions and do something else entirely, that's fine too.
 
-Then ask what matters to them, what they'll use you for, how they want you to behave, any boundaries or preferences. Save their answers to `SOUL.md`.
+7. **Create Home Base silently.** After the suggestion interaction (user picked one, deferred, or typed something else), create their Home Base using `app_create` with `set_as_home_base: true` and `auto_open: false`. Include personalized starter tasks based on what you learned. Do NOT open it with `app_open`. Do NOT announce it, mention it, or hint that something was created. No "check this out," no "I put something together," no "here's what I came up with." Just create it quietly and move on.
 
-If they're not sure yet, that's totally fine. Don't push it, just say you'll figure it out as you go and move on.
+Ask one question at a time. Don't dump a form on them.
 
-## Setting Up Home Base
+## Privacy
 
-Once the SOUL.md conversation is done (or the user opted to skip it), create their Home Base. Don't ask, just do it. Don't announce that you're about to build something. Don't say "let me put something together" or "give me a sec." Just create it silently, then present the result as if you were already thinking ahead about what they'd need.
+Only the assistant's name is hard-required. Everything else about the user (their name, work role, hobbies, daily tools) is best-effort. Ask naturally, not as a form. If something is unclear, you can ask one short follow-up, but if the user declines or dodges, do not push. Just move on.
 
-Generate the Home Base app using `app_create` with `set_as_home_base: true`. Include **personalized starter tasks** based on what you learned about the user, things they'd actually want to do. Think about:
+A field is "resolved" when any of these is true:
+- The user gave an explicit answer
+- You confidently inferred it from conversation
+- The user declined, dodged, or sidestepped it (treat all of these as declined)
 
-- What they told you they use you for (email, research, writing, coding, etc.)
-- Practical daily tasks: "Check my emails", "Start my day", "Set a reminder"
-- Setup tasks they haven't done yet: "Set up voice chat", "Enable computer control"
-- Fun/discovery tasks: "Surprise me", "Teach me something new"
+When saving to `USER.md`, mark declined fields so you don't re-ask later (e.g., `Work role: declined_by_user`). Inferred values can note the source (e.g., `Daily tools: inferred: Slack, Figma`).
 
-If the user didn't share much, use sensible defaults. Don't make it feel empty.
+## Saving What You Learn
 
-Don't use generic filler. Every button should feel like something *this specific user* would click. Use `relay_prompt` actions so each button sends a natural-language prompt to you.
+Save what you learn as you go. Update `IDENTITY.md` (name, nature, personality, emoji, style tendency) and `USER.md` (their name, how to address them, goals, locale, work role, hobbies, daily tools) using `file_edit`. If the conversation reveals how the user wants you to behave (e.g., "be direct," "don't be too chatty"), save those behavioral guidelines to `SOUL.md` — that file is about your personality and how you operate, not the user's data. Just do it quietly. Don't tell the user which files you're editing or mention tool names.
 
-After creating it, immediately open it with `app_open` so they can see it right away. Present it like you've been thinking ahead, you already figured out what they might need. Something like:
+When saving to `IDENTITY.md`, be specific about the tone, energy, and conversational style you discovered during onboarding. This file persists after onboarding, so everything about how you should come across needs to be captured there -- not just your name and emoji, but the full vibe: how you talk, how much energy you bring, whether you're blunt or gentle, funny or serious.
 
-> "While we were talking, I was already thinking about what you might need. I came up with X ideas. Check this out."
+## Completion Gate
 
-Where X is the total number of starter + onboarding tasks you included in the Home Base. Don't call it "Home Base" by name, just show it. Let them know they can customize it anytime.
+Do NOT delete this file until ALL of the following are true:
+- You have a name (hard requirement)
+- You've figured out your vibe and adopted it
+- User detail fields are resolved: name, work role, hobbies/interests, and daily tools. Resolved means the user provided a value, you confidently inferred one, or the user declined/dodged it. All four must be in one of those states.
+- 2 suggestions shown (via `ui_show` or as text if UI unavailable)
+- The user selected one, deferred both, or typed an alternate direction
+- Home Base has been created silently
 
-Then delete this file. You're done here.
+Once every condition is met, delete this file. You're done here.
 
 ---
 

package/src/config/templates/USER.md

@@ -14,9 +14,14 @@ _(What do they care about? What projects are they working on? What annoys them?
 
 ## Onboarding Snapshot
 
+_Each field below should end up in one of three states: an explicit value, an inferred value (note the source), or `declined_by_user`. All fields must be resolved before onboarding completes, but declining is a valid resolution._
+
 - Preferred name/reference:
 - Goals:
 - Locale:
+- Work role:
+- Hobbies/fun:
+- Daily tools:
 
 ---
 

package/src/config/update-bulletin-template-path.ts

@@ -1,6 +1,9 @@
 import { join } from 'node:path';
 
+import { resolveBundledDir } from '../util/bundled-asset.js';
+
 /** Returns the path to the bundled UPDATES.md template. Extracted for testability. */
 export function getTemplatePath(): string {
-  return join(import.meta.dirname ?? __dirname, 'templates', 'UPDATES.md');
+  const dir = resolveBundledDir(import.meta.dirname ?? __dirname, 'templates', 'templates');
+  return join(dir, 'UPDATES.md');
 }

package/src/config/vellum-skills/trusted-contacts/SKILL.md

@@ -123,16 +123,35 @@ curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members/<member_id>/block
 
 Use this when the guardian wants to invite someone to message the assistant on Telegram without needing their user ID upfront. The invite link is a shareable Telegram deep link — when someone opens it, they automatically get trusted-contact access.
 
+**Important**: The shell snippet below emits a `<vellum-sensitive-output>` directive containing the raw invite token. The tool executor automatically strips this directive and replaces the raw token with a placeholder so the LLM never sees it. The placeholder is resolved back to the real token in the final assistant reply.
+
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites" \
+
+BOT_CONFIG_JSON=$(curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/config" \
+  -H "Authorization: Bearer $TOKEN")
+BOT_USERNAME=$(printf '%s' "$BOT_CONFIG_JSON" | tr -d '\n' | sed -n 's/.*"botUsername"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+if [ -z "$BOT_USERNAME" ]; then
+  echo "error:no_bot_username"
+  exit 1
+fi
+
+INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '{
     "sourceChannel": "telegram",
     "maxUses": 1,
     "note": "<optional note, e.g. the person it is for>"
-  }'
+  }')
+INVITE_TOKEN=$(printf '%s' "$INVITE_JSON" | tr -d '\n' | sed -n 's/.*"token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+if [ -z "$INVITE_TOKEN" ]; then
+  printf '%s\n' "$INVITE_JSON"
+  exit 1
+fi
+
+echo "<vellum-sensitive-output kind=\"invite_code\" value=\"$INVITE_TOKEN\" />"
+echo "https://t.me/$BOT_USERNAME?start=iv_$INVITE_TOKEN"
 ```
 
 Optional fields:
@@ -140,21 +159,7 @@ Optional fields:
 - `expiresInMs` — expiration time in milliseconds from now (e.g., `86400000` for 24 hours). Defaults to 7 days (`604800000`) if omitted.
 - `note` — a human-readable label for the invite (e.g., "For Mom", "Family group").
 
-The response contains `{ ok: true, invite: { id, token, ... } }`. The `token` field is the raw invite token — it is only returned at creation time and cannot be retrieved later.
-
-**Building the shareable link**: After creating the invite, look up the Telegram bot username so you can build the deep link. Query the Telegram integration config:
-
-```bash
-TOKEN=$(cat ~/.vellum/http-token)
-curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/config" \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-The response includes `botUsername`. Use it to construct the deep link:
-
-```
-https://t.me/<botUsername>?start=iv_<token>
-```
+The create response contains `{ ok: true, invite: { id, token, ... } }`. The `token` field is the raw invite token — it is only returned at creation time and cannot be retrieved later.
 
 **Presenting to the guardian**: Give the guardian the link with clear copy-paste instructions: