@vellumai/assistant 0.5.16 → 0.6.0

package/src/config/bundled-skills/outlook/tools/outlook-sender-digest.ts

@@ -0,0 +1,272 @@
+import {
+  batchGetMessages,
+  listMessages,
+  searchMessages,
+} from "../../../../messaging/providers/outlook/client.js";
+import type { OutlookMessage } from "../../../../messaging/providers/outlook/types.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { storeScanResult } from "../../gmail/tools/scan-result-store.js";
+import { err, ok } from "./shared.js";
+
+const MAX_MESSAGES_CAP = 10000;
+const MAX_IDS_PER_SENDER = 5000;
+const MAX_SAMPLE_SUBJECTS = 3;
+
+interface SenderAggregation {
+  displayName: string;
+  email: string;
+  messageCount: number;
+  hasUnsubscribe: boolean;
+  newestMessageId: string;
+  newestUnsubscribableMessageId: string | null;
+  newestUnsubscribableEpoch: number;
+  oldestDate: string;
+  newestDate: string;
+  messageIds: string[];
+  hasMore: boolean;
+  sampleSubjects: string[];
+}
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const userQuery = input.query as string | undefined;
+  const maxSenders = (input.max_senders as number) ?? 50;
+
+  try {
+    const connection = await resolveOAuthConnection("outlook", {
+      account,
+    });
+
+    // Build OData filter: inbox messages from last 90 days
+    const ninetyDaysAgo = new Date(
+      Date.now() - 90 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    const ninetyDaysAgoEpoch = new Date(ninetyDaysAgo).getTime();
+    const dateFilter = `receivedDateTime ge ${ninetyDaysAgo}`;
+
+    const allMessageIds: string[] = [];
+    const fetchPromises: Promise<OutlookMessage[]>[] = [];
+    let skip = 0;
+    let truncated = false;
+    let timeBudgetExceeded = false;
+    const startTime = Date.now();
+    const TIME_BUDGET_MS = 90_000;
+
+    // When userQuery is provided, use searchMessages (Microsoft Graph
+    // doesn't support combining $filter and $search). Date filtering is
+    // applied client-side instead.
+    const useSearch = Boolean(userQuery);
+
+    // Paginate through messages
+    while (allMessageIds.length < MAX_MESSAGES_CAP) {
+      if (Date.now() - startTime > TIME_BUDGET_MS) {
+        timeBudgetExceeded = true;
+        truncated = true;
+        break;
+      }
+      const pageSize = Math.min(100, MAX_MESSAGES_CAP - allMessageIds.length);
+
+      let messages: OutlookMessage[];
+
+      if (useSearch) {
+        const searchResp = await searchMessages(connection, userQuery!, {
+          top: pageSize,
+          skip,
+        });
+        messages = searchResp.value ?? [];
+      } else {
+        const listResp = await listMessages(connection, {
+          top: pageSize,
+          skip,
+          filter: dateFilter,
+          orderby: "receivedDateTime desc",
+          select: "id,from,receivedDateTime,hasAttachments,subject",
+        });
+        messages = listResp.value ?? [];
+      }
+
+      if (messages.length === 0) break;
+
+      // When using search, apply 90-day date filter client-side
+      const filtered = useSearch
+        ? messages.filter((m) => {
+            const received = m.receivedDateTime
+              ? new Date(m.receivedDateTime).getTime()
+              : 0;
+            return received >= ninetyDaysAgoEpoch;
+          })
+        : messages;
+
+      const ids = filtered.map((m) => m.id);
+      allMessageIds.push(...ids);
+
+      // Fetch internet message headers (List-Unsubscribe) for each batch
+      if (ids.length > 0) {
+        fetchPromises.push(
+          batchGetMessages(
+            connection,
+            ids,
+            "id,from,receivedDateTime,subject,internetMessageHeaders",
+          ),
+        );
+      }
+
+      skip += messages.length;
+
+      // If we received fewer messages than requested, there are no more pages
+      if (messages.length < pageSize) break;
+
+      // When using search, if all messages in a page are older than
+      // 90 days we've likely passed beyond the relevant window
+      if (useSearch && filtered.length === 0) break;
+    }
+
+    // Flag truncation if we hit the cap with more pages potentially available
+    if (allMessageIds.length >= MAX_MESSAGES_CAP) {
+      truncated = true;
+    }
+
+    if (allMessageIds.length === 0) {
+      return ok(
+        JSON.stringify({
+          senders: [],
+          total_scanned: 0,
+          message:
+            "No emails found matching the query. Try broadening the search (e.g. extend date range).",
+        }),
+      );
+    }
+
+    const fetchedMessages = (await Promise.all(fetchPromises)).flat();
+
+    // Group by sender email
+    const senderMap = new Map<string, SenderAggregation>();
+
+    for (const msg of fetchedMessages) {
+      const fromEmail = msg.from?.emailAddress?.address?.toLowerCase();
+      const fromName = msg.from?.emailAddress?.name ?? "";
+      const subject = msg.subject ?? "";
+      const dateStr = msg.receivedDateTime ?? "";
+
+      if (!fromEmail) continue;
+
+      // Check for List-Unsubscribe header
+      const listUnsub = msg.internetMessageHeaders?.find(
+        (h) => h.name.toLowerCase() === "list-unsubscribe",
+      )?.value;
+
+      let agg = senderMap.get(fromEmail);
+      if (!agg) {
+        agg = {
+          displayName: fromName,
+          email: fromEmail,
+          messageCount: 0,
+          hasUnsubscribe: false,
+          newestMessageId: msg.id,
+          newestUnsubscribableMessageId: null,
+          newestUnsubscribableEpoch: 0,
+          oldestDate: dateStr,
+          newestDate: dateStr,
+          messageIds: [],
+          hasMore: false,
+          sampleSubjects: [],
+        };
+        senderMap.set(fromEmail, agg);
+      }
+
+      agg.messageCount++;
+
+      if (listUnsub) agg.hasUnsubscribe = true;
+
+      // Use displayName from earliest message that has one
+      if (!agg.displayName && fromName) agg.displayName = fromName;
+
+      // Track message IDs (cap at MAX_IDS_PER_SENDER)
+      if (agg.messageIds.length < MAX_IDS_PER_SENDER) {
+        agg.messageIds.push(msg.id);
+      } else {
+        agg.hasMore = true;
+      }
+
+      // Track date range using ISO date strings
+      const msgEpoch = dateStr ? new Date(dateStr).getTime() : 0;
+      const oldestEpoch = agg.oldestDate
+        ? new Date(agg.oldestDate).getTime()
+        : Infinity;
+      const newestEpoch = agg.newestDate
+        ? new Date(agg.newestDate).getTime()
+        : 0;
+
+      if (msgEpoch > 0 && msgEpoch < oldestEpoch) {
+        agg.oldestDate = dateStr || agg.oldestDate;
+      }
+      if (msgEpoch > newestEpoch) {
+        agg.newestDate = dateStr || agg.newestDate;
+        agg.newestMessageId = msg.id;
+      }
+
+      // Track the newest message that has List-Unsubscribe so
+      // unsubscribe actions target a message that carries the header
+      if (listUnsub && msgEpoch >= agg.newestUnsubscribableEpoch) {
+        agg.newestUnsubscribableMessageId = msg.id;
+        agg.newestUnsubscribableEpoch = msgEpoch;
+      }
+
+      // Collect sample subjects
+      if (subject && agg.sampleSubjects.length < MAX_SAMPLE_SUBJECTS) {
+        agg.sampleSubjects.push(subject);
+      }
+    }
+
+    // Sort by message count descending, take top N
+    const sorted = [...senderMap.values()]
+      .sort((a, b) => b.messageCount - a.messageCount)
+      .slice(0, maxSenders);
+
+    const resultSenders = sorted.map((s) => ({
+      id: Buffer.from(s.email).toString("base64url"),
+      display_name: s.displayName || s.email.split("@")[0],
+      email: s.email,
+      message_count: s.messageCount,
+      has_unsubscribe: s.hasUnsubscribe,
+      newest_message_id:
+        s.hasUnsubscribe && s.newestUnsubscribableMessageId
+          ? s.newestUnsubscribableMessageId
+          : s.newestMessageId,
+      oldest_date: s.oldestDate,
+      newest_date: s.newestDate,
+      sample_subjects: s.sampleSubjects,
+    }));
+
+    // Store message IDs server-side to keep them out of LLM context
+    const scanId = storeScanResult(
+      sorted.map((s) => ({
+        id: Buffer.from(s.email).toString("base64url"),
+        messageIds: s.messageIds,
+        newestMessageId: s.newestMessageId,
+        newestUnsubscribableMessageId: s.newestUnsubscribableMessageId,
+      })),
+    );
+
+    return ok(
+      JSON.stringify({
+        scan_id: scanId,
+        senders: resultSenders,
+        total_scanned: allMessageIds.length,
+        query_used: userQuery ?? `inbox messages from last 90 days`,
+        ...(truncated ? { truncated: true } : {}),
+        ...(timeBudgetExceeded ? { time_budget_exceeded: true } : {}),
+        note: `message_count reflects emails found per sender within the ${allMessageIds.length} messages scanned. Use scan_id with outlook_archive to archive messages (pass scan_id + sender_ids instead of message_ids).`,
+      }),
+    );
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/outlook/tools/outlook-trash.ts

@@ -0,0 +1,29 @@
+import { trashMessage } from "../../../../messaging/providers/outlook/client.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { err, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const messageId = input.message_id as string;
+
+  if (!messageId) {
+    return err("message_id is required.");
+  }
+
+  try {
+    const connection = await resolveOAuthConnection("outlook", {
+      account,
+    });
+    await trashMessage(connection, messageId);
+    return ok("Message moved to Deleted Items.");
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/outlook/tools/outlook-unsubscribe.ts

@@ -0,0 +1,129 @@
+import {
+  getMessageWithHeaders,
+  sendMessage,
+} from "../../../../messaging/providers/outlook/client.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
+import {
+  isPrivateOrLocalHost,
+  resolveHostAddresses,
+} from "../../../../tools/network/url-safety.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import {
+  err,
+  ok,
+  pinnedHttpsRequest,
+  resolveRequestAddress,
+} from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  if (!context.triggeredBySurfaceAction) {
+    return err(
+      "This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
+    );
+  }
+
+  const messageId = input.message_id as string;
+
+  if (!messageId) {
+    return err("message_id is required.");
+  }
+
+  try {
+    const connection = await resolveOAuthConnection("outlook", {
+      account,
+    });
+    const message = await getMessageWithHeaders(connection, messageId);
+    const headers = message.internetMessageHeaders ?? [];
+    const unsubHeader = headers.find(
+      (h) => h.name.toLowerCase() === "list-unsubscribe",
+    )?.value;
+
+    if (!unsubHeader) {
+      return err(
+        "No List-Unsubscribe header found. Manual unsubscribe may be required.",
+      );
+    }
+
+    const httpsMatch = unsubHeader.match(/<(https:\/\/[^>]+)>/);
+    const mailtoMatch = unsubHeader.match(/<mailto:([^>]+)>/);
+    const postHeader = headers.find(
+      (h) => h.name.toLowerCase() === "list-unsubscribe-post",
+    )?.value;
+
+    if (httpsMatch) {
+      const url = httpsMatch[1];
+      let parsed: URL;
+      let validatedAddresses: string[];
+      try {
+        parsed = new URL(url);
+        if (parsed.protocol !== "https:") {
+          return err("Unsubscribe URL must use HTTPS.");
+        }
+        if (isPrivateOrLocalHost(parsed.hostname)) {
+          return err("Unsubscribe URL points to a private or local address.");
+        }
+        const { addresses, blockedAddress } = await resolveRequestAddress(
+          parsed.hostname,
+          resolveHostAddresses,
+          false,
+        );
+        if (blockedAddress) {
+          return err("Unsubscribe URL resolves to a private or local address.");
+        }
+        if (addresses.length === 0) {
+          return err("Unable to resolve unsubscribe URL hostname.");
+        }
+        validatedAddresses = addresses;
+      } catch {
+        return err("Invalid unsubscribe URL.");
+      }
+
+      const method = postHeader ? "POST" : "GET";
+      const reqOpts = postHeader
+        ? {
+            method: "POST" as const,
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: postHeader,
+          }
+        : undefined;
+
+      let lastStatus = 0;
+      for (const address of validatedAddresses) {
+        try {
+          lastStatus = await pinnedHttpsRequest(parsed, address, reqOpts);
+          if (lastStatus >= 200 && lastStatus < 400) {
+            return ok(`Successfully unsubscribed via HTTPS ${method}.`);
+          }
+        } catch {
+          continue;
+        }
+      }
+      return err(`Unsubscribe request failed: ${lastStatus}`);
+    }
+
+    if (mailtoMatch) {
+      const mailtoAddr = mailtoMatch[1].split("?")[0];
+      await sendMessage(connection, {
+        message: {
+          subject: "Unsubscribe",
+          body: { contentType: "text", content: "" },
+          toRecipients: [{ emailAddress: { address: mailtoAddr } }],
+        },
+      });
+      return ok(`Unsubscribe email sent to ${mailtoAddr}.`);
+    }
+
+    return err(
+      "No supported unsubscribe method found (requires https: or mailto: URL).",
+    );
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/outlook/tools/outlook-vacation.ts

@@ -0,0 +1,87 @@
+import {
+  getAutoReplySettings,
+  updateAutoReplySettings,
+} from "../../../../messaging/providers/outlook/client.js";
+import type { OutlookAutoReplySettings } from "../../../../messaging/providers/outlook/types.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { err, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const action = input.action as string;
+
+  if (!action) {
+    return err("action is required (get, enable, or disable).");
+  }
+
+  try {
+    const connection = await resolveOAuthConnection("outlook", {
+      account,
+    });
+    switch (action) {
+      case "get": {
+        const settings = await getAutoReplySettings(connection);
+        return ok(JSON.stringify(settings, null, 2));
+      }
+
+      case "enable": {
+        const internalMessage = input.internal_message as string;
+        if (!internalMessage)
+          return err("internal_message is required when enabling auto-reply.");
+
+        const externalAudience = (input.external_audience as string) ?? "none";
+        const startDate = input.start_date as string | undefined;
+        const endDate = input.end_date as string | undefined;
+        const timeZone =
+          (input.time_zone as string) ??
+          Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+        const isScheduled = !!(startDate && endDate);
+
+        const settings: OutlookAutoReplySettings = {
+          status: isScheduled ? "scheduled" : "alwaysEnabled",
+          externalAudience: externalAudience as "none" | "contactsOnly" | "all",
+          internalReplyMessage: internalMessage,
+        };
+
+        if (input.external_message) {
+          settings.externalReplyMessage = input.external_message as string;
+        }
+
+        if (isScheduled) {
+          settings.scheduledStartDateTime = {
+            dateTime: startDate!,
+            timeZone,
+          };
+          settings.scheduledEndDateTime = {
+            dateTime: endDate!,
+            timeZone,
+          };
+        }
+
+        await updateAutoReplySettings(connection, settings);
+        return ok("Auto-reply enabled.");
+      }
+
+      case "disable": {
+        await updateAutoReplySettings(connection, {
+          status: "disabled",
+          externalAudience: "none",
+        });
+        return ok("Auto-reply disabled.");
+      }
+
+      default:
+        return err(`Unknown action "${action}". Use get, enable, or disable.`);
+    }
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/outlook/tools/shared.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared utilities for Outlook skill tools.
+ */
+
+import type { ToolExecutionResult } from "../../../../tools/types.js";
+
+export function ok(content: string): ToolExecutionResult {
+  return { content, isError: false };
+}
+
+export function err(message: string): ToolExecutionResult {
+  return { content: message, isError: true };
+}
+
+// Re-export DNS rebinding protection helpers from the Gmail shared module.
+// These are provider-agnostic and should be reused, not duplicated.
+export { pinnedHttpsRequest } from "../../gmail/tools/shared.js";
+
+// resolveRequestAddress lives in the shared network-safety module (not Gmail-specific).
+export { resolveRequestAddress } from "../../../../tools/network/url-safety.js";

package/src/config/bundled-skills/outlook-calendar/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: outlook-calendar
+description: View, create, and manage Outlook Calendar events and check availability
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "📅"
+  vellum:
+    display-name: "Outlook Calendar"
+---
+
+You are an Outlook Calendar assistant with full access to the user's calendar. Use the Outlook Calendar tools to help them view, create, and manage events.
+
+## Connection Setup
+
+Before using any Outlook Calendar tool, verify that Outlook is connected by attempting a lightweight call (e.g., `outlook_calendar_list_events` with a narrow date range). If the call fails with a token/authorization error:
+
+1. **Try connecting directly first.** Run `assistant oauth status outlook`. This will show whether or not the user had previously connected their Outlook account. If so, they are ready to go.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
+
+## Capabilities
+
+- **List Events**: View upcoming events from any calendar within a date range.
+- **Get Event**: Read full details of a specific calendar event.
+- **Create Event**: Create new events with attendees, location, and description.
+- **Check Availability**: Find free/busy times across calendars to identify open slots for scheduling.
+- **RSVP**: Respond to event invitations (accepted, declined, tentative).
+
+## Scheduling Playbook
+
+When the user wants to schedule something:
+
+1. **Always check availability first** before proposing times. Use `outlook_calendar_check_availability` to find free slots.
+2. Propose 2-3 available time options to the user.
+3. Once the user picks a time, create the event with `outlook_calendar_create_event`.
+4. If adding other attendees, mention that they'll receive an invitation email.
+
+## Date & Time Handling
+
+- Always ask the user for their timezone if it's not already known from context or their profile.
+- Use ISO 8601 format for dates and times (e.g., `2024-01-15T09:00:00-05:00`).
+- For all-day events, use date-only format (e.g., `2024-01-15`).
+- When listing events, display times in the user's local timezone.
+
+## Confidence Scores
+
+Medium-risk tools (create event, RSVP) require a confidence score between 0 and 1. Set this based on how certain you are the action matches the user's intent:
+
+- **0.9-1.0**: User explicitly requested this exact action
+- **0.7-0.8**: Action is strongly implied by context
+- **0.5-0.6**: Reasonable inference but some ambiguity
+- **Below 0.5**: Ask the user to confirm before proceeding