@vellumai/assistant 0.4.35 → 0.4.37

package/src/runtime/channel-invite-transports/telegram.ts

@@ -1,18 +1,23 @@
 /**
  * Telegram channel invite adapter.
  *
- * Builds `https://t.me/<botUsername>?start=iv_<token>` deep links and
- * extracts invite tokens from `/start iv_<token>` command payloads.
+ * Builds `https://t.me/<botUsername>?start=iv_<token>` deep links,
+ * extracts invite tokens from `/start iv_<token>` command payloads,
+ * and resolves the bot's channel handle for invite instructions.
  *
  * The `iv_` prefix distinguishes invite tokens from `gv_` (guardian
  * verification) tokens that use the same `/start` deep-link mechanism.
  */
 
 import type { ChannelId } from "../../channels/types.js";
-import { getCredentialMetadata } from "../../tools/credentials/metadata-store.js";
+import { getSecureKey } from "../../security/secure-keys.js";
+import {
+  getCredentialMetadata,
+  upsertCredentialMetadata,
+} from "../../tools/credentials/metadata-store.js";
+import { getLogger } from "../../util/logger.js";
 import type {
   ChannelInviteAdapter,
-  GuardianInstruction,
   InviteShareLink,
 } from "../channel-invite-transport.js";
 
@@ -37,6 +42,66 @@ function getTelegramBotUsername(): string | undefined {
   return process.env.TELEGRAM_BOT_USERNAME || undefined;
 }
 
+/**
+ * Ensure the Telegram bot username is resolved and cached in credential
+ * metadata. When the bot token was configured via CLI `credential set`,
+ * `credential_store` tool, or ingress secret redirect, the `getMe` API
+ * call that populates `accountInfo` is skipped — this function fills that
+ * gap so that invite share links can be generated.
+ */
+export async function ensureTelegramBotUsernameResolved(): Promise<void> {
+  const meta = getCredentialMetadata("telegram", "bot_token");
+  if (
+    meta?.accountInfo &&
+    typeof meta.accountInfo === "string" &&
+    meta.accountInfo.trim().length > 0
+  ) {
+    return; // Username already cached
+  }
+
+  const token = getSecureKey("credential:telegram:bot_token");
+  if (!token) return;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    let res: Response;
+    try {
+      res = await fetch(`https://api.telegram.org/bot${token}/getMe`, {
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!res.ok) {
+      getLogger("telegram-invite").warn(
+        "Failed to resolve Telegram bot username: HTTP %d",
+        res.status,
+      );
+      return;
+    }
+    const body = (await res.json()) as {
+      ok: boolean;
+      result?: { username?: string };
+    };
+    const username = body.result?.username;
+    if (!username) {
+      getLogger("telegram-invite").warn(
+        "Telegram getMe response did not include a username",
+      );
+      return;
+    }
+    upsertCredentialMetadata("telegram", "bot_token", {
+      accountInfo: username,
+    });
+  } catch (err) {
+    getLogger("telegram-invite").warn(
+      { err },
+      "Failed to resolve Telegram bot username via getMe API",
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Token prefix
 // ---------------------------------------------------------------------------
@@ -68,23 +133,6 @@ export const telegramInviteAdapter: ChannelInviteAdapter = {
     };
   },
 
-  buildGuardianInstruction(params: {
-    inviteCode: string;
-    contactName?: string;
-  }): GuardianInstruction {
-    const botUsername = getTelegramBotUsername();
-    const contactLabel = params.contactName || "the contact";
-    if (!botUsername) {
-      return {
-        instruction: `Tell ${contactLabel} to message the assistant on Telegram and provide the code ${params.inviteCode}.`,
-      };
-    }
-    return {
-      instruction: `Tell ${contactLabel} to message @${botUsername} on Telegram and provide the code ${params.inviteCode}.`,
-      channelHandle: `@${botUsername}`,
-    };
-  },
-
   resolveChannelHandle(): string | undefined {
     const botUsername = getTelegramBotUsername();
     if (!botUsername) return undefined;
@@ -126,10 +174,3 @@ export const telegramInviteAdapter: ChannelInviteAdapter = {
     return undefined;
   },
 };
-
-// ---------------------------------------------------------------------------
-// Backward-compatible alias
-// ---------------------------------------------------------------------------
-
-/** @deprecated Use `telegramInviteAdapter` instead. */
-export const telegramInviteTransport = telegramInviteAdapter;

package/src/runtime/channel-invite-transports/voice.ts

@@ -49,10 +49,3 @@ export const voiceInviteAdapter: ChannelInviteAdapter = {
     return undefined;
   },
 };
-
-// ---------------------------------------------------------------------------
-// Backward-compatible alias
-// ---------------------------------------------------------------------------
-
-/** @deprecated Use `voiceInviteAdapter` instead. */
-export const voiceInviteTransport = voiceInviteAdapter;

package/src/runtime/channel-invite-transports/whatsapp.ts

@@ -0,0 +1,43 @@
+/**
+ * WhatsApp channel invite adapter.
+ *
+ * WhatsApp uses Meta WhatsApp Business API credentials, not Twilio.
+ * The Meta API identifies numbers by phone_number_id (a numeric string),
+ * which isn't a user-facing phone number. The display number is resolved
+ * from workspace config (`whatsapp.phoneNumber`), falling back to
+ * `undefined` (triggering generic instructions) when not configured.
+ */
+
+import type { ChannelId } from "../../channels/types.js";
+import { getConfig } from "../../config/loader.js";
+import type { ChannelInviteAdapter } from "../channel-invite-transport.js";
+
+// ---------------------------------------------------------------------------
+// Phone number resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the user-configured WhatsApp display phone number from workspace
+ * config. The Meta API's `phone_number_id` is not user-facing, so the
+ * display number must be explicitly configured by the user.
+ */
+export function resolveWhatsAppDisplayNumber(): string | undefined {
+  try {
+    const config = getConfig();
+    return config.whatsapp.phoneNumber || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+
+export const whatsappInviteAdapter: ChannelInviteAdapter = {
+  channel: "whatsapp" as ChannelId,
+
+  resolveChannelHandle(): string | undefined {
+    return resolveWhatsAppDisplayNumber();
+  },
+};

package/src/runtime/channel-readiness-service.ts

@@ -3,9 +3,12 @@ import {
   getTollFreeVerificationStatus,
   hasTwilioCredentials,
 } from "../calls/twilio-rest.js";
+import { getChannelInvitePolicy } from "../channels/config.js";
 import { getTwilioPhoneNumberEnv } from "../config/env.js";
 import { loadRawConfig } from "../config/loader.js";
+import { getEmailService } from "../email/service.js";
 import { getSecureKey } from "../security/secure-keys.js";
+import { resolveWhatsAppDisplayNumber } from "./channel-invite-transports/whatsapp.js";
 import type {
   ChannelId,
   ChannelProbe,
@@ -19,25 +22,13 @@ export const REMOTE_TTL_MS = 5 * 60 * 1000;
 
 // ── SMS Probe ───────────────────────────────────────────────────────────────
 
-function hasIngressConfigured(): boolean {
-  try {
-    const raw = loadRawConfig();
-    const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
-    const publicBaseUrl = (ingress.publicBaseUrl as string) ?? "";
-    const enabled =
-      (ingress.enabled as boolean | undefined) ??
-      (publicBaseUrl ? true : false);
-    return enabled && publicBaseUrl.length > 0;
-  } catch {
-    return false;
-  }
+// Keep Twilio phone-number resolution inside an already-authorized module so
+// the secure-key import boundary does not expand for shared config helpers.
+function resolveSmsPhoneNumber(): string {
+  return resolveTwilioPhoneNumber();
 }
 
-/**
- * Resolve SMS from-number with canonical precedence:
- * env override -> config sms.phoneNumber -> secure key fallback.
- */
-function resolveSmsPhoneNumber(): string {
+function resolveTwilioPhoneNumber(): string {
   try {
     const raw = loadRawConfig();
     const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
@@ -56,6 +47,20 @@ function resolveSmsPhoneNumber(): string {
   }
 }
 
+function hasIngressConfigured(): boolean {
+  try {
+    const raw = loadRawConfig();
+    const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
+    const publicBaseUrl = (ingress.publicBaseUrl as string) ?? "";
+    const enabled =
+      (ingress.enabled as boolean | undefined) ??
+      (publicBaseUrl ? true : false);
+    return enabled && publicBaseUrl.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 const smsProbe: ChannelProbe = {
   channel: "sms",
   runLocalChecks(): ReadinessCheckResult[] {
@@ -171,32 +176,6 @@ const smsProbe: ChannelProbe = {
 
 // ── Voice Probe ─────────────────────────────────────────────────────────────
 
-/**
- * Resolve voice from-number with the same precedence as SMS:
- * env override -> config sms.phoneNumber -> secure key fallback.
- *
- * Voice and SMS share the same Twilio phone number infrastructure, so the
- * resolution logic is identical to resolveSmsPhoneNumber.
- */
-function resolveVoicePhoneNumber(): string {
-  try {
-    const raw = loadRawConfig();
-    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-    return (
-      getTwilioPhoneNumberEnv() ||
-      (smsConfig.phoneNumber as string) ||
-      getSecureKey("credential:twilio:phone_number") ||
-      ""
-    );
-  } catch {
-    return (
-      getTwilioPhoneNumberEnv() ||
-      getSecureKey("credential:twilio:phone_number") ||
-      ""
-    );
-  }
-}
-
 const voiceProbe: ChannelProbe = {
   channel: "voice",
   runLocalChecks(): ReadinessCheckResult[] {
@@ -211,7 +190,7 @@ const voiceProbe: ChannelProbe = {
         : "Twilio Account SID and Auth Token are not configured",
     });
 
-    const resolvedNumber = resolveVoicePhoneNumber();
+    const resolvedNumber = resolveSmsPhoneNumber();
     const hasPhone = !!resolvedNumber;
     results.push({
       name: "phone_number",
@@ -275,6 +254,181 @@ const telegramProbe: ChannelProbe = {
   // Telegram has no remote checks currently
 };
 
+// ── Email Probe ─────────────────────────────────────────────────────────────
+
+const emailProbe: ChannelProbe = {
+  channel: "email",
+  runLocalChecks(): ReadinessCheckResult[] {
+    const results: ReadinessCheckResult[] = [];
+
+    const hasApiKey = !!(
+      getSecureKey("agentmail") || getSecureKey("credential:agentmail:api_key")
+    );
+    results.push({
+      name: "agentmail_api_key",
+      passed: hasApiKey,
+      message: hasApiKey
+        ? "AgentMail API key is configured"
+        : "AgentMail API key is not configured",
+    });
+
+    const invitePolicy = getChannelInvitePolicy("email");
+    results.push({
+      name: "invite_policy",
+      passed: invitePolicy.codeRedemptionEnabled,
+      message: invitePolicy.codeRedemptionEnabled
+        ? "Email invite code redemption is enabled"
+        : "Email invite code redemption is disabled",
+    });
+
+    const hasIngress = hasIngressConfigured();
+    results.push({
+      name: "ingress",
+      passed: hasIngress,
+      message: hasIngress
+        ? "Public ingress URL is configured"
+        : "Public ingress URL is not configured or disabled",
+    });
+
+    return results;
+  },
+  async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
+    // Only worth checking if the API key is present
+    const hasApiKey = !!(
+      getSecureKey("agentmail") || getSecureKey("credential:agentmail:api_key")
+    );
+    if (!hasApiKey) return [];
+
+    try {
+      const address = await getEmailService().getPrimaryInboxAddress();
+      const hasInbox = !!address;
+      return [
+        {
+          name: "inbox_configured",
+          passed: hasInbox,
+          message: hasInbox
+            ? `Inbox address is configured (${address})`
+            : "No inbox address configured — create one with: vellum email setup inboxes",
+        },
+      ];
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return [
+        {
+          name: "inbox_configured",
+          passed: false,
+          message: `Failed to check inbox configuration: ${message}`,
+        },
+      ];
+    }
+  },
+};
+
+// ── WhatsApp Probe ──────────────────────────────────────────────────────────
+
+const whatsappProbe: ChannelProbe = {
+  channel: "whatsapp",
+  runLocalChecks(): ReadinessCheckResult[] {
+    const results: ReadinessCheckResult[] = [];
+
+    const hasPhoneNumberId = !!getSecureKey(
+      "credential:whatsapp:phone_number_id",
+    );
+    results.push({
+      name: "whatsapp_phone_number_id",
+      passed: hasPhoneNumberId,
+      message: hasPhoneNumberId
+        ? "WhatsApp phone number ID is configured"
+        : "WhatsApp phone number ID is not configured",
+    });
+
+    const hasAccessToken = !!getSecureKey("credential:whatsapp:access_token");
+    results.push({
+      name: "whatsapp_access_token",
+      passed: hasAccessToken,
+      message: hasAccessToken
+        ? "WhatsApp access token is configured"
+        : "WhatsApp access token is not configured",
+    });
+
+    const hasAppSecret = !!getSecureKey("credential:whatsapp:app_secret");
+    results.push({
+      name: "whatsapp_app_secret",
+      passed: hasAppSecret,
+      message: hasAppSecret
+        ? "WhatsApp app secret is configured"
+        : "WhatsApp app secret is not configured",
+    });
+
+    const hasWebhookVerifyToken = !!getSecureKey(
+      "credential:whatsapp:webhook_verify_token",
+    );
+    results.push({
+      name: "whatsapp_webhook_verify_token",
+      passed: hasWebhookVerifyToken,
+      message: hasWebhookVerifyToken
+        ? "WhatsApp webhook verify token is configured"
+        : "WhatsApp webhook verify token is not configured",
+    });
+
+    const displayNumber = resolveWhatsAppDisplayNumber();
+    const hasDisplayNumber = !!displayNumber;
+    results.push({
+      name: "whatsapp_display_phone_number",
+      passed: hasDisplayNumber,
+      message: hasDisplayNumber
+        ? `WhatsApp display phone number is configured (${displayNumber})`
+        : "WhatsApp display phone number is not configured — set whatsapp.phoneNumber in workspace config",
+    });
+
+    const invitePolicy = getChannelInvitePolicy("whatsapp");
+    results.push({
+      name: "invite_policy",
+      passed: invitePolicy.codeRedemptionEnabled,
+      message: invitePolicy.codeRedemptionEnabled
+        ? "WhatsApp invite code redemption is enabled"
+        : "WhatsApp invite code redemption is disabled",
+    });
+
+    const hasIngress = hasIngressConfigured();
+    results.push({
+      name: "ingress",
+      passed: hasIngress,
+      message: hasIngress
+        ? "Public ingress URL is configured"
+        : "Public ingress URL is not configured or disabled",
+    });
+
+    return results;
+  },
+};
+
+// ── Slack Probe ─────────────────────────────────────────────────────────────
+
+const slackProbe: ChannelProbe = {
+  channel: "slack",
+  runLocalChecks(): ReadinessCheckResult[] {
+    const hasBotToken = !!getSecureKey("credential:slack_channel:bot_token");
+    const hasAppToken = !!getSecureKey("credential:slack_channel:app_token");
+    return [
+      {
+        name: "bot_token",
+        passed: hasBotToken,
+        message: hasBotToken
+          ? "Slack bot token is configured"
+          : "Slack bot token is not configured",
+      },
+      {
+        name: "app_token",
+        passed: hasAppToken,
+        message: hasAppToken
+          ? "Slack app token is configured"
+          : "Slack app token is not configured",
+      },
+    ];
+  },
+};
+
 // ── Service ─────────────────────────────────────────────────────────────────
 
 export class ChannelReadinessService {
@@ -416,11 +570,14 @@ export class ChannelReadinessService {
 
 // ── Factory ─────────────────────────────────────────────────────────────────
 
-/** Create a service instance with built-in SMS, Voice, and Telegram probes registered. */
+/** Create a service instance with built-in SMS, Voice, Telegram, Email, WhatsApp, and Slack probes registered. */
 export function createReadinessService(): ChannelReadinessService {
   const service = new ChannelReadinessService();
   service.registerProbe(smsProbe);
   service.registerProbe(voiceProbe);
   service.registerProbe(telegramProbe);
+  service.registerProbe(emailProbe);
+  service.registerProbe(whatsappProbe);
+  service.registerProbe(slackProbe);
   return service;
 }

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -18,6 +18,7 @@ import {
   createCanonicalGuardianDelivery,
 } from "../memory/canonical-guardian-store.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import type { NotificationSourceChannel } from "../notifications/signal.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
@@ -144,7 +145,7 @@ export function bridgeConfirmationRequestToGuardian(
   // Emit guardian.question notification so the guardian is alerted.
   const signalPromise = emitNotificationSignal({
     sourceEventName: "guardian.question",
-    sourceChannel,
+    sourceChannel: sourceChannel as NotificationSourceChannel,
     sourceSessionId: conversationId,
     attentionHints: {
       requiresAction: true,

package/src/runtime/guardian-outbound-actions.ts

@@ -259,9 +259,9 @@ function initiateGuardianVoiceCall(
 // Start outbound
 // ---------------------------------------------------------------------------
 
-export function startOutbound(
+export async function startOutbound(
   params: StartOutboundParams,
-): OutboundActionResult {
+): Promise<OutboundActionResult> {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
   const channel = params.channel;
   const originConversationId = params.originConversationId;
@@ -275,7 +275,7 @@ export function startOutbound(
       originConversationId,
     );
   } else if (channel === "telegram") {
-    return startOutboundTelegram(
+    return await startOutboundTelegram(
       params.destination,
       assistantId,
       channel,
@@ -397,13 +397,13 @@ function startOutboundSms(
   };
 }
 
-function startOutboundTelegram(
+async function startOutboundTelegram(
   destination: string | undefined,
   assistantId: string,
   channel: ChannelId,
   rebind?: boolean,
   originConversationId?: string,
-): OutboundActionResult {
+): Promise<OutboundActionResult> {
   if (!destination) {
     return {
       success: false,
@@ -495,6 +495,9 @@ function startOutboundTelegram(
   }
 
   // Telegram handle/username: create a pending_bootstrap session with deep-link
+  const { ensureTelegramBotUsernameResolved } =
+    await import("./channel-invite-transports/telegram.js");
+  await ensureTelegramBotUsernameResolved();
   const botUsername = getTelegramBotUsername();
   if (!botUsername) {
     return {

package/src/runtime/http-server.ts

@@ -130,6 +130,7 @@ import { surfaceActionRouteDefinitions } from "./routes/surface-action-routes.js
 import { surfaceContentRouteDefinitions } from "./routes/surface-content-routes.js";
 import { trustRulesRouteDefinitions } from "./routes/trust-rules-routes.js";
 import { twilioRouteDefinitions } from "./routes/twilio-routes.js";
+import { usageRouteDefinitions } from "./routes/usage-routes.js";
 
 // Re-export for consumers
 export { isPrivateAddress } from "./middleware/auth.js";
@@ -684,6 +685,7 @@ export class RuntimeHttpServer {
       ...secretRouteDefinitions(),
       ...identityRouteDefinitions(),
       ...debugRouteDefinitions(),
+      ...usageRouteDefinitions(),
 
       // Browser relay — not extracted into a domain module because
       // these two routes depend on the in-process extensionRelayServer