@vellumai/assistant 0.4.49 → 0.4.51

package/src/calls/call-domain.ts

@@ -21,7 +21,7 @@ import { revokeScopedApprovalGrantsForContext } from "../memory/scoped-approval-
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { isGuardian } from "../runtime/channel-verification-service.js";
 import { credentialKey } from "../security/credential-key.js";
-import { getSecureKey } from "../security/secure-keys.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { upsertActiveCallLease } from "./active-call-lease.js";
 import { isDeniedNumber } from "./call-constants.js";
@@ -177,7 +177,7 @@ export async function resolveCallerIdentity(
   }
 
   if (mode === "assistant_number") {
-    const twilioConfig = getTwilioConfig();
+    const twilioConfig = await getTwilioConfig();
     log.info(
       { mode, source, fromNumber: twilioConfig.phoneNumber },
       "Resolved caller identity",
@@ -193,7 +193,7 @@ export async function resolveCallerIdentity(
     userNumber = identityConfig.userNumber;
     numberSource = "user_config";
   } else {
-    const secureKeyValue = getSecureKey(
+    const secureKeyValue = await getSecureKeyAsync(
       credentialKey("twilio", "user_phone_number"),
     );
     if (secureKeyValue) {
@@ -1017,3 +1017,134 @@ export async function startVerificationCall(
     };
   }
 }
+
+// ── Invite call ───────────────────────────────────────────────────────
+
+export type StartInviteCallInput = {
+  phoneNumber: string;
+  friendName: string;
+  guardianName: string;
+  assistantId?: string;
+};
+
+export type StartInviteCallResult = { ok: true; callSid: string } | CallError;
+
+/**
+ * Initiate an outbound call to deliver a voice invite to a contact.
+ *
+ * Creates a minimal call session with a voice channel binding and
+ * passes invite-specific custom parameters so the relay server can
+ * detect this is an invite redemption call.
+ */
+export async function startInviteCall(
+  input: StartInviteCallInput,
+): Promise<StartInviteCallResult> {
+  const { phoneNumber, friendName, guardianName } = input;
+
+  if (!phoneNumber || !E164_REGEX.test(phoneNumber)) {
+    return {
+      ok: false,
+      error: "phone_number must be in E.164 format",
+      status: 400,
+    };
+  }
+
+  let sessionId: string | null = null;
+
+  try {
+    const config = loadConfig();
+    const provider = new TwilioConversationRelayProvider();
+
+    // Resolve the assistant's Twilio number as the caller ID
+    const identityResult = await resolveCallerIdentity(config);
+    if (!identityResult.ok) {
+      return { ok: false, error: identityResult.error, status: 400 };
+    }
+
+    const preflightResult = await preflightVoiceIngress();
+    if (!preflightResult.ok) {
+      return preflightResult;
+    }
+    const ingressConfig = preflightResult.ingressConfig;
+
+    // Create a minimal conversation so the call session has a valid FK,
+    // and bind it to the voice channel so it never appears as an unbound
+    // desktop thread.
+    const timestamp = Date.now();
+    const convKey = `invite-call:${phoneNumber}:${timestamp}`;
+    const { conversationId } = getOrCreateConversation(convKey);
+
+    upsertBinding({
+      conversationId,
+      sourceChannel: "phone",
+      externalChatId: `invite-call:${phoneNumber}:${timestamp}`,
+    });
+
+    const session = createCallSession({
+      conversationId,
+      provider: "twilio",
+      fromNumber: identityResult.fromNumber,
+      toNumber: phoneNumber,
+      callMode: "invite",
+      inviteFriendName: friendName,
+      inviteGuardianName: guardianName,
+    });
+    sessionId = session.id;
+
+    const webhookUrl = await resolveCallbackUrl(
+      () => getTwilioVoiceWebhookUrl(ingressConfig, session.id),
+      "webhooks/twilio/voice",
+      "twilio_voice",
+      { callSessionId: session.id },
+    );
+    const statusCallbackUrl = await resolveCallbackUrl(
+      () => getTwilioStatusCallbackUrl(ingressConfig),
+      "webhooks/twilio/status",
+      "twilio_status",
+    );
+
+    upsertActiveCallLease({ callSessionId: session.id });
+
+    const { callSid } = await provider.initiateCall({
+      from: identityResult.fromNumber,
+      to: phoneNumber,
+      webhookUrl,
+      statusCallbackUrl,
+    });
+
+    updateCallSession(session.id, { providerCallSid: callSid });
+
+    log.info(
+      {
+        callSessionId: session.id,
+        callSid,
+        to: phoneNumber,
+        friendName,
+        guardianName,
+      },
+      "Invite call initiated",
+    );
+
+    return { ok: true, callSid };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err, phoneNumber, friendName, guardianName },
+      "Failed to initiate invite call",
+    );
+
+    if (sessionId) {
+      updateCallSession(sessionId, {
+        status: "failed",
+        endedAt: Date.now(),
+        lastError: msg,
+      });
+    }
+
+    return {
+      ok: false,
+      error: `Error initiating invite call: ${msg}`,
+      status: 500,
+    };
+  }
+}

package/src/calls/call-store.ts

@@ -37,6 +37,8 @@ const parseCallSession = createRowMapper<
   status: { from: "status", transform: cast<CallSession["status"]>() },
   callMode: { from: "callMode", transform: cast<CallSession["callMode"]>() },
   verificationSessionId: "verificationSessionId",
+  inviteFriendName: "inviteFriendName",
+  inviteGuardianName: "inviteGuardianName",
   callerIdentityMode: "callerIdentityMode",
   callerIdentitySource: "callerIdentitySource",
   initiatedFromConversationId: "initiatedFromConversationId",
@@ -81,6 +83,8 @@ export function createCallSession(opts: {
   task?: string;
   callMode?: string;
   verificationSessionId?: string;
+  inviteFriendName?: string;
+  inviteGuardianName?: string;
   callerIdentityMode?: string;
   callerIdentitySource?: string;
   initiatedFromConversationId?: string;
@@ -98,6 +102,8 @@ export function createCallSession(opts: {
     status: "initiated" as const,
     callMode: (opts.callMode ?? null) as CallSession["callMode"],
     verificationSessionId: opts.verificationSessionId ?? null,
+    inviteFriendName: opts.inviteFriendName ?? null,
+    inviteGuardianName: opts.inviteGuardianName ?? null,
     callerIdentityMode: opts.callerIdentityMode ?? null,
     callerIdentitySource: opts.callerIdentitySource ?? null,
     initiatedFromConversationId: opts.initiatedFromConversationId ?? null,

package/src/calls/relay-server.ts

@@ -575,6 +575,7 @@ export class RelayConnection {
           outcome.fromNumber,
           outcome.friendName,
           outcome.guardianName,
+          !resolved.isInbound,
         );
         return;
       case "name_capture":
@@ -772,6 +773,12 @@ export class RelayConnection {
     fromNumber: string;
     callerName?: string;
     skipMemberActivation?: boolean;
+    activationReason?:
+      | "invite_redeemed"
+      | "access_approved"
+      | "trusted_contact_verified";
+    friendName?: string;
+    guardianName?: string;
   }): void {
     const { assistantId, fromNumber, callerName } = params;
 
@@ -808,7 +815,25 @@ export class RelayConnection {
     updateCallSession(this.callSessionId, { status: "in_progress" });
 
     const guardianLabel = this.resolveGuardianLabel();
-    const handoffText = `Great! ${guardianLabel} said I can speak with you. How can I help?`;
+    let handoffText: string;
+
+    if (params.activationReason === "invite_redeemed") {
+      const name = params.friendName;
+      const assistantName = this.resolveAssistantLabel();
+      const gLabel = params.guardianName || guardianLabel;
+      if (name) {
+        handoffText = assistantName
+          ? `Great, I've verified that you are ${name}. It's nice to meet you! I'm ${assistantName}, ${gLabel}'s assistant. How can I help?`
+          : `Great, I've verified that you are ${name}. It's nice to meet you! How can I help?`;
+      } else {
+        handoffText = assistantName
+          ? `Great, I've verified your identity. It's nice to meet you! I'm ${assistantName}, ${gLabel}'s assistant. How can I help?`
+          : `Great, I've verified your identity. It's nice to meet you! How can I help?`;
+      }
+    } else {
+      handoffText = `Great! ${guardianLabel} said I can speak with you. How can I help?`;
+    }
+
     this.sendTextToken(handoffText, true);
 
     recordCallEvent(this.callSessionId, "assistant_spoke", {
@@ -1000,6 +1025,7 @@ export class RelayConnection {
         this.continueCallAfterTrustedContactActivation({
           assistantId,
           fromNumber,
+          activationReason: "trusted_contact_verified",
         });
       } else {
         // Inbound guardian verification: binding already handled above,
@@ -1096,6 +1122,7 @@ export class RelayConnection {
     fromNumber: string,
     friendName: string | null,
     guardianName: string | null,
+    isOutbound: boolean,
   ): void {
     this.inviteRedemptionActive = true;
     this.inviteRedemptionAssistantId = assistantId;
@@ -1116,14 +1143,21 @@ export class RelayConnection {
 
     const displayFriend = friendName ?? "there";
     const displayGuardian = guardianName ?? "your contact";
-    this.sendTextToken(
-      `Welcome ${displayFriend}. Please enter the 6-digit code that ${displayGuardian} provided you to verify your identity.`,
-      true,
-    );
+
+    let promptText: string;
+    if (isOutbound) {
+      const assistantName = this.resolveAssistantLabel();
+      promptText = assistantName
+        ? `Hi ${displayFriend}, this is ${assistantName}, ${displayGuardian}'s assistant. To get started, please enter the 6-digit code that ${displayGuardian} shared with you.`
+        : `Hi ${displayFriend}, this is ${displayGuardian}'s assistant. To get started, please enter the 6-digit code that ${displayGuardian} shared with you.`;
+    } else {
+      promptText = `Welcome ${displayFriend}. Please enter the 6-digit code that ${displayGuardian} provided you to verify your identity.`;
+    }
+    this.sendTextToken(promptText, true);
 
     log.info(
       { callSessionId: this.callSessionId, assistantId },
-      "Inbound voice invite redemption started",
+      `${isOutbound ? "Outbound" : "Inbound"} voice invite redemption started`,
     );
   }
 
@@ -1358,6 +1392,7 @@ export class RelayConnection {
       assistantId,
       fromNumber,
       callerName: callerName ?? undefined,
+      activationReason: "access_approved",
     });
 
     recordCallEvent(
@@ -1541,6 +1576,9 @@ export class RelayConnection {
         fromNumber: this.inviteRedemptionFromNumber,
         callerName: this.inviteRedemptionFriendName ?? undefined,
         skipMemberActivation: true,
+        activationReason: "invite_redeemed",
+        friendName: this.inviteRedemptionFriendName ?? undefined,
+        guardianName: this.inviteRedemptionGuardianName ?? undefined,
       });
     } else {
       this.inviteRedemptionActive = false;

package/src/calls/relay-setup-router.ts

@@ -99,8 +99,24 @@ export function routeSetup(ctx: SetupContext): {
     actorTrust,
   };
 
-  // ── Outbound guardian verification (persisted mode) ──────────────
+  // ── Outbound flow selection based on persisted call mode ──────────
   const persistedMode = ctx.session?.callMode;
+
+  // ── Outbound invite redemption (persisted mode) ─────────────────
+  if (persistedMode === "invite") {
+    return {
+      outcome: {
+        action: "invite_redemption" as const,
+        assistantId,
+        fromNumber: ctx.to,
+        friendName: ctx.session?.inviteFriendName ?? null,
+        guardianName: ctx.session?.inviteGuardianName ?? null,
+      },
+      resolved,
+    };
+  }
+
+  // ── Outbound guardian verification (persisted mode) ──────────────
   const persistedVsId = ctx.session?.verificationSessionId;
   const customParamVsId = ctx.customParameters?.verificationSessionId;
   const verificationSessionId = persistedVsId ?? customParamVsId;

package/src/calls/twilio-config.ts

@@ -4,7 +4,7 @@ import {
   getTwilioRelayUrl,
 } from "../inbound/public-ingress-urls.js";
 import { credentialKey } from "../security/credential-key.js";
-import { getSecureKey } from "../security/secure-keys.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { ConfigError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 
@@ -20,7 +20,7 @@ export interface TwilioConfig {
 
 /**
  * Resolve the Twilio phone number using a unified fallback chain so that
- * all callers (calls, SMS adapter, readiness checks, invite transports)
+ * all callers (calls, readiness checks, invite transports)
  * agree on the same number.
  *
  * Resolution order:
@@ -38,10 +38,11 @@ export function resolveTwilioPhoneNumber(): string {
   return "";
 }
 
-export function getTwilioConfig(): TwilioConfig {
+export async function getTwilioConfig(): Promise<TwilioConfig> {
   const config = loadConfig();
   const accountSid = config.twilio?.accountSid || "";
-  const authToken = getSecureKey(credentialKey("twilio", "auth_token")) || "";
+  const authToken =
+    (await getSecureKeyAsync(credentialKey("twilio", "auth_token"))) || "";
   const phoneNumber = resolveTwilioPhoneNumber();
   const webhookBaseUrl = getPublicBaseUrl(config);
 

package/src/calls/twilio-provider.ts

@@ -1,7 +1,7 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 
 import { credentialKey } from "../security/credential-key.js";
-import { getSecureKey } from "../security/secure-keys.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { ProviderError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import {
@@ -24,8 +24,11 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
 
   // ── Credential helpers ──────────────────────────────────────────────
 
-  private getCredentials(): { accountSid: string; authToken: string } {
-    return getTwilioCredentials();
+  private async getCredentials(): Promise<{
+    accountSid: string;
+    authToken: string;
+  }> {
+    return await getTwilioCredentials();
   }
 
   private authHeader(accountSid: string, authToken: string): string {
@@ -39,7 +42,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   // ── VoiceProvider interface ─────────────────────────────────────────
 
   async initiateCall(opts: InitiateCallOptions): Promise<{ callSid: string }> {
-    const { accountSid, authToken } = this.getCredentials();
+    const { accountSid, authToken } = await this.getCredentials();
 
     const body = new URLSearchParams({
       From: opts.from,
@@ -104,7 +107,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   }
 
   async endCall(callSid: string): Promise<void> {
-    const { accountSid, authToken } = this.getCredentials();
+    const { accountSid, authToken } = await this.getCredentials();
 
     log.info({ callSid }, "Ending Twilio call");
 
@@ -139,7 +142,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   }
 
   async getCallStatus(callSid: string): Promise<string> {
-    const { accountSid, authToken } = this.getCredentials();
+    const { accountSid, authToken } = await this.getCredentials();
 
     const res = await fetch(
       `${this.baseUrl(accountSid)}/Calls/${callSid}.json`,
@@ -179,7 +182,7 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   async checkCallerIdEligibility(
     phoneNumber: string,
   ): Promise<{ eligible: boolean; reason?: string }> {
-    const { accountSid, authToken } = this.getCredentials();
+    const { accountSid, authToken } = await this.getCredentials();
     const encodedNumber = encodeURIComponent(phoneNumber);
 
     let incomingOk = false;
@@ -280,8 +283,10 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
    * Exposed as a static method so callers (e.g. the HTTP server webhook
    * middleware) can check availability independently.
    */
-  static getAuthToken(): string | null {
-    return getSecureKey(credentialKey("twilio", "auth_token")) || null;
+  static async getAuthToken(): Promise<string | null> {
+    return (
+      (await getSecureKeyAsync(credentialKey("twilio", "auth_token"))) || null
+    );
   }
 
   /**

package/src/calls/twilio-rest.ts

@@ -8,7 +8,7 @@
 
 import { loadConfig } from "../config/loader.js";
 import { credentialKey } from "../security/credential-key.js";
-import { getSecureKey } from "../security/secure-keys.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { ConfigError, ProviderError } from "../util/errors.js";
 
 export interface TwilioCredentials {
@@ -28,14 +28,17 @@ function resolveAccountSid(): string | undefined {
 }
 
 /** Resolve the Twilio Auth Token from the credential store. */
-function resolveAuthToken(): string | undefined {
-  return getSecureKey(credentialKey("twilio", "auth_token")) || undefined;
+async function resolveAuthToken(): Promise<string | undefined> {
+  return (
+    (await getSecureKeyAsync(credentialKey("twilio", "auth_token"))) ||
+    undefined
+  );
 }
 
 /** Resolve Twilio credentials from config (SID) and credential store (token). Throws if not configured. */
-export function getTwilioCredentials(): TwilioCredentials {
+export async function getTwilioCredentials(): Promise<TwilioCredentials> {
   const accountSid = resolveAccountSid();
-  const authToken = resolveAuthToken();
+  const authToken = await resolveAuthToken();
   if (!accountSid || !authToken) {
     throw new ConfigError(
       "Twilio credentials not configured. Set twilio.accountSid via config and store auth token via credential store.",
@@ -45,9 +48,9 @@ export function getTwilioCredentials(): TwilioCredentials {
 }
 
 /** Check whether Twilio credentials are present (non-throwing). */
-export function hasTwilioCredentials(): boolean {
+export async function hasTwilioCredentials(): Promise<boolean> {
   try {
-    return !!resolveAccountSid() && !!resolveAuthToken();
+    return !!resolveAccountSid() && !!(await resolveAuthToken());
   } catch {
     return false;
   }

package/src/calls/types.ts

@@ -58,7 +58,7 @@ export type PendingQuestionStatus =
  * uses this as the primary signal for deterministic flow selection,
  * with Twilio setup custom parameters as a secondary/observability signal.
  */
-export type CallMode = "normal" | "verification";
+export type CallMode = "normal" | "verification" | "invite";
 
 export interface CallSession {
   id: string;
@@ -71,6 +71,8 @@ export interface CallSession {
   status: CallStatus;
   callMode: CallMode | null;
   verificationSessionId: string | null;
+  inviteFriendName: string | null;
+  inviteGuardianName: string | null;
   callerIdentityMode: string | null;
   callerIdentitySource: string | null;
   initiatedFromConversationId?: string | null;

package/src/cli/commands/config.ts

@@ -39,10 +39,13 @@ export function registerConfigCommand(program: Command): void {
     "after",
     `
 Configuration is stored in config.json in the assistant workspace directory.
-Keys support dotted paths for nested values (e.g. calls.enabled, apiKeys.anthropic).
+Keys support dotted paths for nested values (e.g. calls.enabled, twilio.accountSid).
 Values are auto-parsed as JSON (booleans, numbers, objects) with fallback to
 plain string if parsing fails.
 
+API keys are managed separately via secure storage. Use "assistant keys list"
+and "assistant keys set <provider> <key>" to view and manage API keys.
+
 Examples:
   $ assistant config list
   $ assistant config get provider
@@ -53,14 +56,14 @@ Examples:
   config
     .command("set <key> <value>")
     .description(
-      "Set a config value (supports dotted paths like apiKeys.anthropic)",
+      "Set a config value (supports dotted paths like calls.enabled)",
     )
     .addHelpText(
       "after",
       `
 Arguments:
   key     Dotted path to the config key (e.g. provider, calls.enabled,
-          apiKeys.anthropic). Intermediate objects are created automatically.
+          twilio.accountSid). Intermediate objects are created automatically.
   value   The value to store. Parsed as JSON first (so "true" becomes boolean
           true, "42" becomes number 42). Falls back to plain string if JSON
           parsing fails.
@@ -68,10 +71,11 @@ Arguments:
 After writing the value to config.json, the lockfile is automatically synced
 to reflect the updated configuration.
 
+To manage API keys, use "assistant keys set <provider> <key>" instead.
+
 Examples:
   $ assistant config set provider anthropic
-  $ assistant config set calls.enabled true
-  $ assistant config set apiKeys.anthropic sk-ant-abc123`,
+  $ assistant config set calls.enabled true`,
     )
     .action((key: string, value: string) => {
       const raw = loadRawConfig();
@@ -100,10 +104,11 @@ Arguments:
 Prints the value at the given key path. If the key is not set, prints
 "(not set)". Object values are pretty-printed as indented JSON.
 
+To view API keys, use "assistant keys list" instead.
+
 Examples:
   $ assistant config get provider
-  $ assistant config get calls.enabled
-  $ assistant config get apiKeys`,
+  $ assistant config get calls.enabled`,
     )
     .action((key: string) => {
       const raw = loadRawConfig();
@@ -133,8 +138,8 @@ Dumps the full raw configuration from config.json as pretty-printed JSON.
 If no configuration has been set, prints "No configuration set".
 
 The --search flag filters results by case-insensitive substring match against
-flattened dotted key paths. For example, --search api matches apiKeys.anthropic,
-apiKeys.openai, and any other key containing "api".
+flattened dotted key paths. For example, --search calls matches calls.enabled,
+calls.recordingEnabled, and any other key containing "calls".
 
 Examples:
   $ assistant config list

package/src/cli/commands/contacts.ts

@@ -497,6 +497,7 @@ Examples:
       "--guardian-name <name>",
       "Guardian name (required for voice invites)",
     )
+    .requiredOption("--contact-id <id>", "Contact ID to bind the invite to")
     .addHelpText(
       "after",
       `
@@ -529,6 +530,7 @@ Examples:
           expectedExternalUserId?: string;
           friendName?: string;
           guardianName?: string;
+          contactId: string;
         },
         cmd: Command,
       ) => {
@@ -563,6 +565,7 @@ Examples:
             expectedExternalUserId: opts.expectedExternalUserId,
             friendName: opts.friendName,
             guardianName: opts.guardianName,
+            contactId: opts.contactId,
           });
           if (result.ok) {
             writeOutput(cmd, { ok: true, invite: result.data });