@vellumai/assistant 0.3.4 → 0.3.6

package/src/messaging/providers/sms/adapter.ts

@@ -0,0 +1,201 @@
+/**
+ * SMS messaging provider adapter.
+ *
+ * Enables proactive outbound SMS messaging via the gateway's /deliver/sms
+ * endpoint. Similar to the Telegram provider, SMS delivery is proxied through
+ * the gateway which owns the Twilio credentials and handles the Messages API.
+ *
+ * Twilio credentials (account_sid, auth_token) and a configured phone number
+ * are required for connectivity. The phone number is resolved from the config
+ * (sms.phoneNumber), env var (TWILIO_PHONE_NUMBER), or secure key fallback.
+ *
+ * The `token` parameter in MessagingProvider methods is unused for SMS
+ * because delivery is authenticated via the gateway's bearer token, not
+ * a per-user OAuth token.
+ */
+
+import type { MessagingProvider } from '../../provider.js';
+import type {
+  Conversation,
+  Message,
+  SearchResult,
+  SendResult,
+  ConnectionInfo,
+  ListOptions,
+  HistoryOptions,
+  SearchOptions,
+  SendOptions,
+} from '../../provider-types.js';
+import { getSecureKey } from '../../../security/secure-keys.js';
+import { readHttpToken } from '../../../util/platform.js';
+import { loadConfig } from '../../../config/loader.js';
+import { getGatewayInternalBaseUrl, getTwilioPhoneNumberEnv } from '../../../config/env.js';
+import { getOrCreateConversation } from '../../../memory/conversation-key-store.js';
+import * as externalConversationStore from '../../../memory/external-conversation-store.js';
+import * as sms from './client.js';
+
+/** Resolve the gateway base URL, preferring GATEWAY_INTERNAL_BASE_URL if set. */
+function getGatewayUrl(): string {
+  return getGatewayInternalBaseUrl();
+}
+
+/** Read the runtime HTTP bearer token used to authenticate with the gateway. */
+function getBearerToken(): string {
+  const token = readHttpToken();
+  if (!token) {
+    throw new Error('No runtime HTTP bearer token available — is the daemon running?');
+  }
+  return token;
+}
+
+/** Check whether Twilio credentials are stored. */
+function hasTwilioCredentials(): boolean {
+  return (
+    !!getSecureKey('credential:twilio:account_sid') &&
+    !!getSecureKey('credential:twilio:auth_token')
+  );
+}
+
+/**
+ * Resolve the configured SMS phone number.
+ * Priority: assistant-scoped phone number > TWILIO_PHONE_NUMBER env > config sms.phoneNumber > secure key fallback.
+ */
+function getPhoneNumber(assistantId?: string): string | undefined {
+  // Check assistant-scoped phone number first
+  if (assistantId) {
+    try {
+      const config = loadConfig();
+      const assistantPhone = config.sms?.assistantPhoneNumbers?.[assistantId];
+      if (assistantPhone) return assistantPhone;
+    } catch {
+      // Config may not be available yet during early startup
+    }
+  }
+
+  const fromEnv = getTwilioPhoneNumberEnv();
+  if (fromEnv) return fromEnv;
+
+  try {
+    const config = loadConfig();
+    if (config.sms?.phoneNumber) return config.sms.phoneNumber;
+  } catch {
+    // Config may not be available yet during early startup
+  }
+
+  return getSecureKey('credential:twilio:phone_number') || undefined;
+}
+
+function hasAnyAssistantPhoneNumber(): boolean {
+  try {
+    const config = loadConfig();
+    return Object.keys(config.sms?.assistantPhoneNumbers ?? {}).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export const smsMessagingProvider: MessagingProvider = {
+  id: 'sms',
+  displayName: 'SMS',
+  credentialService: 'twilio',
+  capabilities: new Set(['send']),
+
+  /**
+   * SMS is connected when Twilio credentials are stored AND a phone number
+   * is configured. Without a phone number the gateway cannot determine
+   * the `from` for outbound messages.
+   */
+  isConnected(): boolean {
+    return hasTwilioCredentials() && (!!getPhoneNumber() || hasAnyAssistantPhoneNumber());
+  },
+
+  async testConnection(_token: string): Promise<ConnectionInfo> {
+    if (!hasTwilioCredentials()) {
+      return {
+        connected: false,
+        user: 'unknown',
+        platform: 'sms',
+        metadata: { error: 'No Twilio credentials found. Run the twilio-setup skill.' },
+      };
+    }
+
+    const phoneNumber = getPhoneNumber();
+    if (!phoneNumber && !hasAnyAssistantPhoneNumber()) {
+      return {
+        connected: false,
+        user: 'unknown',
+        platform: 'sms',
+        metadata: { error: 'No phone number configured. Run the twilio-setup skill to assign a number.' },
+      };
+    }
+
+    const accountSid = getSecureKey('credential:twilio:account_sid')!;
+
+    return {
+      connected: true,
+      user: phoneNumber ?? 'assistant-scoped numbers configured',
+      platform: 'sms',
+      metadata: {
+        accountSid: accountSid.slice(0, 6) + '...',
+        ...(phoneNumber ? { phoneNumber } : {}),
+        hasAssistantScopedPhoneNumbers: hasAnyAssistantPhoneNumber(),
+      },
+    };
+  },
+
+  async sendMessage(_token: string, conversationId: string, text: string, options?: SendOptions): Promise<SendResult> {
+    const gatewayUrl = getGatewayUrl();
+    const bearerToken = getBearerToken();
+    const assistantId = options?.assistantId;
+
+    const sendResult = await sms.sendMessage(gatewayUrl, bearerToken, conversationId, text, assistantId);
+
+    // Upsert external conversation binding so the conversation key mapping
+    // exists for the next inbound SMS from this number.
+    try {
+      const sourceChannel = 'sms';
+      const conversationKey = assistantId && assistantId !== 'self'
+        ? `asst:${assistantId}:${sourceChannel}:${conversationId}`
+        : `${sourceChannel}:${conversationId}`;
+      const { conversationId: internalId } = getOrCreateConversation(conversationKey);
+      // external_conversation_bindings is assistant-agnostic (unique by
+      // sourceChannel + externalChatId). Restrict proactive writes to self so
+      // multi-assistant sends cannot clobber each other's binding metadata.
+      if (!assistantId || assistantId === 'self') {
+        externalConversationStore.upsertOutboundBinding({
+          conversationId: internalId,
+          sourceChannel,
+          externalChatId: conversationId,
+        });
+      }
+    } catch {
+      // Best-effort — don't fail the send if binding upsert fails
+    }
+
+    // Use the Twilio message SID as the send result ID when available,
+    // falling back to a timestamp-based ID for older gateway versions.
+    const id = sendResult.messageSid || `sms-${Date.now()}`;
+
+    return {
+      id,
+      timestamp: Date.now(),
+      conversationId,
+    };
+  },
+
+  // SMS does not support listing conversations. The assistant can only
+  // send to known phone numbers (conversation IDs).
+  async listConversations(_token: string, _options?: ListOptions): Promise<Conversation[]> {
+    return [];
+  },
+
+  // SMS does not provide message history retrieval via the gateway.
+  async getHistory(_token: string, _conversationId: string, _options?: HistoryOptions): Promise<Message[]> {
+    return [];
+  },
+
+  // SMS does not support message search.
+  async search(_token: string, _query: string, _options?: SearchOptions): Promise<SearchResult> {
+    return { total: 0, messages: [], hasMore: false };
+  },
+};

package/src/messaging/providers/sms/client.ts

@@ -0,0 +1,93 @@
+/**
+ * Low-level SMS operations.
+ *
+ * Outbound message delivery routes through the gateway's /deliver/sms
+ * endpoint, which handles Twilio credential management and the Messages API.
+ * The gateway resolves the `from` number using the optional assistantId or
+ * its default Twilio phone number configuration.
+ */
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+
+export class SmsApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'SmsApiError';
+  }
+}
+
+/** Payload accepted by the gateway's /deliver/sms endpoint. */
+interface DeliverPayload {
+  to: string;
+  text: string;
+  assistantId?: string;
+}
+
+/** Result returned by sendMessage with Twilio acceptance details. */
+export interface SmsSendResult {
+  messageSid?: string;
+  status?: string;
+  errorCode?: string | null;
+  errorMessage?: string | null;
+}
+
+/**
+ * Send an SMS message via the gateway's /deliver/sms endpoint.
+ *
+ * Returns Twilio acceptance details propagated from the gateway.
+ * "Accepted" means Twilio received it for delivery -- it has NOT yet
+ * been confirmed as delivered to the handset.
+ */
+export async function sendMessage(
+  gatewayUrl: string,
+  bearerToken: string,
+  to: string,
+  text: string,
+  assistantId?: string,
+): Promise<SmsSendResult> {
+  const payload: DeliverPayload = { to, text };
+  if (assistantId) {
+    payload.assistantId = assistantId;
+  }
+
+  const url = `${gatewayUrl}/deliver/sms`;
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '<unreadable>');
+    throw new SmsApiError(
+      resp.status,
+      `Gateway /deliver/sms failed (${resp.status}): ${body}`,
+    );
+  }
+
+  try {
+    const data = (await resp.json()) as {
+      ok?: boolean;
+      messageSid?: string;
+      status?: string;
+      errorCode?: string | null;
+      errorMessage?: string | null;
+    };
+    return {
+      messageSid: data.messageSid,
+      status: data.status,
+      errorCode: data.errorCode,
+      errorMessage: data.errorMessage,
+    };
+  } catch {
+    // Older gateway versions may not return JSON with Twilio details
+    return {};
+  }
+}

package/src/messaging/providers/sms/types.ts

@@ -0,0 +1,7 @@
+/** Twilio SMS types used by the messaging provider. */
+
+export interface TwilioAccountInfo {
+  accountSid: string;
+  friendlyName: string;
+  phoneNumber: string;
+}

package/src/messaging/providers/telegram-bot/adapter.ts

@@ -25,17 +25,14 @@ import type {
 } from '../../provider-types.js';
 import { getSecureKey } from '../../../security/secure-keys.js';
 import { readHttpToken } from '../../../util/platform.js';
+import { getGatewayInternalBaseUrl } from '../../../config/env.js';
 import { getOrCreateConversation } from '../../../memory/conversation-key-store.js';
 import * as externalConversationStore from '../../../memory/external-conversation-store.js';
 import * as telegram from './client.js';
 
 /** Resolve the gateway base URL, preferring GATEWAY_INTERNAL_BASE_URL if set. */
 function getGatewayUrl(): string {
-  if (process.env.GATEWAY_INTERNAL_BASE_URL) {
-    return process.env.GATEWAY_INTERNAL_BASE_URL.replace(/\/+$/, "");
-  }
-  const port = Number(process.env.GATEWAY_PORT) || 7830;
-  return `http://127.0.0.1:${port}`;
+  return getGatewayInternalBaseUrl();
 }
 
 /** Read the runtime HTTP bearer token used to authenticate with the gateway. */

package/src/messaging/providers/whatsapp/adapter.ts

@@ -0,0 +1,136 @@
+/**
+ * WhatsApp Business messaging provider adapter.
+ *
+ * Enables proactive outbound WhatsApp messaging via the gateway's /deliver/whatsapp
+ * endpoint. Delivery is proxied through the gateway which owns the Meta Cloud API
+ * credentials (phone_number_id + access_token).
+ *
+ * The `token` parameter in MessagingProvider methods is unused for WhatsApp
+ * because delivery is authenticated via the gateway's bearer token, not
+ * a per-user OAuth token.
+ */
+
+import type { MessagingProvider } from '../../provider.js';
+import type {
+  Conversation,
+  Message,
+  SearchResult,
+  SendResult,
+  ConnectionInfo,
+  ListOptions,
+  HistoryOptions,
+  SearchOptions,
+  SendOptions,
+} from '../../provider-types.js';
+import { getSecureKey } from '../../../security/secure-keys.js';
+import { readHttpToken } from '../../../util/platform.js';
+import { getGatewayInternalBaseUrl } from '../../../config/env.js';
+import { getOrCreateConversation } from '../../../memory/conversation-key-store.js';
+import * as externalConversationStore from '../../../memory/external-conversation-store.js';
+import * as whatsapp from './client.js';
+
+/** Resolve the gateway base URL. */
+function getGatewayUrl(): string {
+  return getGatewayInternalBaseUrl();
+}
+
+/** Read the runtime HTTP bearer token used to authenticate with the gateway. */
+function getBearerToken(): string {
+  const token = readHttpToken();
+  if (!token) {
+    throw new Error('No runtime HTTP bearer token available — is the daemon running?');
+  }
+  return token;
+}
+
+/** Check whether WhatsApp credentials are stored. */
+function hasWhatsAppCredentials(): boolean {
+  return (
+    !!getSecureKey('credential:whatsapp:phone_number_id') &&
+    !!getSecureKey('credential:whatsapp:access_token')
+  );
+}
+
+export const whatsappMessagingProvider: MessagingProvider = {
+  id: 'whatsapp',
+  displayName: 'WhatsApp',
+  credentialService: 'whatsapp',
+  capabilities: new Set(['send']),
+
+  /**
+   * WhatsApp is connected when Meta Cloud API credentials are stored.
+   */
+  isConnected(): boolean {
+    return hasWhatsAppCredentials();
+  },
+
+  async testConnection(_token: string): Promise<ConnectionInfo> {
+    if (!hasWhatsAppCredentials()) {
+      return {
+        connected: false,
+        user: 'unknown',
+        platform: 'whatsapp',
+        metadata: { error: 'No WhatsApp credentials found. Configure WHATSAPP_PHONE_NUMBER_ID and WHATSAPP_ACCESS_TOKEN.' },
+      };
+    }
+
+    const phoneNumberId = getSecureKey('credential:whatsapp:phone_number_id')!;
+
+    return {
+      connected: true,
+      user: phoneNumberId,
+      platform: 'whatsapp',
+      metadata: {
+        phoneNumberId: phoneNumberId.slice(0, 6) + '...',
+      },
+    };
+  },
+
+  async sendMessage(_token: string, conversationId: string, text: string, options?: SendOptions): Promise<SendResult> {
+    const gatewayUrl = getGatewayUrl();
+    const bearerToken = getBearerToken();
+    const assistantId = options?.assistantId;
+
+    await whatsapp.sendMessage(gatewayUrl, bearerToken, conversationId, text, assistantId);
+
+    // Upsert external conversation binding so the conversation key mapping
+    // exists for the next inbound WhatsApp message from this number.
+    try {
+      const sourceChannel = 'whatsapp';
+      const conversationKey = assistantId && assistantId !== 'self'
+        ? `asst:${assistantId}:${sourceChannel}:${conversationId}`
+        : `${sourceChannel}:${conversationId}`;
+      const { conversationId: internalId } = getOrCreateConversation(conversationKey);
+      if (!assistantId || assistantId === 'self') {
+        externalConversationStore.upsertOutboundBinding({
+          conversationId: internalId,
+          sourceChannel,
+          externalChatId: conversationId,
+        });
+      }
+    } catch {
+      // Best-effort — don't fail the send if binding upsert fails
+    }
+
+    return {
+      id: `whatsapp-${Date.now()}`,
+      timestamp: Date.now(),
+      conversationId,
+    };
+  },
+
+  // WhatsApp does not support listing conversations via this provider.
+  async listConversations(_token: string, _options?: ListOptions): Promise<Conversation[]> {
+    return [];
+  },
+
+  // WhatsApp does not provide message history retrieval via the gateway.
+  async getHistory(_token: string, _conversationId: string, _options?: HistoryOptions): Promise<Message[]> {
+    return [];
+  },
+
+  // WhatsApp does not support message search.
+  async search(_token: string, _query: string, _options?: SearchOptions): Promise<SearchResult> {
+    return { total: 0, messages: [], hasMore: false };
+  },
+};

package/src/messaging/providers/whatsapp/client.ts

@@ -0,0 +1,67 @@
+/**
+ * Low-level WhatsApp operations.
+ *
+ * Outbound message delivery routes through the gateway's /deliver/whatsapp
+ * endpoint, which handles WhatsApp credential management and the Meta Cloud API.
+ */
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+
+export class WhatsAppApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'WhatsAppApiError';
+  }
+}
+
+/** Payload accepted by the gateway's /deliver/whatsapp endpoint. */
+interface DeliverPayload {
+  to: string;
+  text: string;
+  assistantId?: string;
+}
+
+/** Result returned by sendMessage. */
+export interface WhatsAppSendResult {
+  ok: boolean;
+}
+
+/**
+ * Send a WhatsApp message via the gateway's /deliver/whatsapp endpoint.
+ */
+export async function sendMessage(
+  gatewayUrl: string,
+  bearerToken: string,
+  to: string,
+  text: string,
+  assistantId?: string,
+): Promise<WhatsAppSendResult> {
+  const payload: DeliverPayload = { to, text };
+  if (assistantId) {
+    payload.assistantId = assistantId;
+  }
+
+  const url = `${gatewayUrl}/deliver/whatsapp`;
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '<unreadable>');
+    throw new WhatsAppApiError(
+      resp.status,
+      `Gateway /deliver/whatsapp failed (${resp.status}): ${body}`,
+    );
+  }
+
+  return { ok: true };
+}

package/src/messaging/style-analyzer.ts

@@ -9,8 +9,7 @@
 import type { Message as ProviderMessage } from './provider-types.js';
 import type { Message, ToolDefinition } from '../providers/types.js';
 import { truncate } from '../util/truncate.js';
-import { getProvider } from '../providers/registry.js';
-import { getConfig } from '../config/loader.js';
+import { getConfiguredProvider } from '../providers/provider-send-message.js';
 
 export interface StylePattern {
   aspect: string;
@@ -118,8 +117,10 @@ export async function extractStylePatterns(
 
   const corpus = corpusEntries.map((e, i) => `--- Message ${i + 1} ---\n${e}`).join('\n\n');
 
-  const config = getConfig();
-  const provider = getProvider(config.provider);
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    return { stylePatterns: [], contactObservations: [] };
+  }
   const promptMessages: Message[] = [{
     role: 'user',
     content: [{ type: 'text', text: `Analyze these ${corpusEntries.length} sent messages for writing style patterns:\n\n${corpus}` }],