@vellumai/assistant 0.5.16 → 0.6.0

package/src/watcher/providers/outlook-calendar.ts

@@ -0,0 +1,343 @@
+/**
+ * Outlook Calendar watcher provider — uses Microsoft Graph delta queries
+ * for efficient change detection.
+ *
+ * On first poll, performs a delta query to capture the initial @odata.deltaLink
+ * as the watermark (start from "now"). Subsequent polls use the deltaLink to
+ * detect new/updated events. Falls back to a fresh delta query if the delta
+ * token has expired (410 Gone).
+ */
+
+import { OutlookCalendarApiError } from "../../config/bundled-skills/outlook-calendar/calendar-client.js";
+import type { OutlookCalendarEvent } from "../../config/bundled-skills/outlook-calendar/types.js";
+import type { OAuthConnection } from "../../oauth/connection.js";
+import { resolveOAuthConnection } from "../../oauth/connection-resolver.js";
+import { getLogger } from "../../util/logger.js";
+import type {
+  FetchResult,
+  WatcherItem,
+  WatcherProvider,
+} from "../provider-types.js";
+
+const CREDENTIAL_SERVICE = "outlook";
+const log = getLogger("watcher:outlook-calendar");
+
+const DELTA_SELECT_FIELDS = [
+  "subject",
+  "start",
+  "end",
+  "location",
+  "bodyPreview",
+  "isAllDay",
+  "showAs",
+  "organizer",
+  "attendees",
+  "webLink",
+  "createdDateTime",
+  "lastModifiedDateTime",
+  "isCancelled",
+  "type",
+].join(",");
+
+function eventToItem(
+  event: OutlookCalendarEvent,
+  eventType: string,
+): WatcherItem {
+  const start = event.start?.dateTime ?? "";
+  const end = event.end?.dateTime ?? "";
+
+  // Include lastModifiedDateTime in the dedup key so subsequent edits to the
+  // same event aren't silently dropped by the watcher_id + external_id constraint.
+  const version = event.lastModifiedDateTime ?? "";
+  const externalId = version ? `${event.id}@${version}` : event.id;
+
+  return {
+    externalId,
+    eventType,
+    summary: `Calendar event: ${event.subject ?? "(no title)"} — ${start}`,
+    payload: {
+      id: event.id,
+      subject: event.subject ?? "",
+      start,
+      end,
+      startTimeZone: event.start?.timeZone ?? "",
+      endTimeZone: event.end?.timeZone ?? "",
+      location: event.location?.displayName ?? "",
+      bodyPreview: event.bodyPreview ?? "",
+      isAllDay: event.isAllDay ?? false,
+      showAs: event.showAs ?? "busy",
+      organizer: event.organizer?.emailAddress?.address ?? "",
+      attendees:
+        event.attendees?.map((a) => ({
+          email: a.emailAddress.address,
+          response: a.status?.response,
+        })) ?? [],
+      webLink: event.webLink ?? "",
+    },
+    timestamp: event.lastModifiedDateTime
+      ? new Date(event.lastModifiedDateTime).getTime()
+      : Date.now(),
+  };
+}
+
+/** Thrown when Microsoft Graph returns 410 Gone (delta token expired). */
+class DeltaSyncExpiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DeltaSyncExpiredError";
+  }
+}
+
+interface DeltaSyncResult {
+  items: OutlookCalendarEvent[];
+  deltaLink: string;
+}
+
+/**
+ * Perform an incremental delta sync using a stored @odata.deltaLink.
+ * Follows pagination (@odata.nextLink) until the final page returns
+ * @odata.deltaLink. Returns all accumulated events and the new deltaLink.
+ */
+async function deltaSync(
+  connection: OAuthConnection,
+  deltaLink: string,
+): Promise<DeltaSyncResult> {
+  const allItems: OutlookCalendarEvent[] = [];
+  let currentUrl = deltaLink;
+  let newDeltaLink: string | undefined;
+
+  do {
+    const parsed = new URL(currentUrl);
+    const path = parsed.pathname;
+    const query: Record<string, string> = {};
+    parsed.searchParams.forEach((v, k) => {
+      query[k] = v;
+    });
+
+    const resp = await connection.request({
+      method: "GET",
+      path,
+      query: Object.keys(query).length > 0 ? query : undefined,
+    });
+
+    if (resp.status < 200 || resp.status >= 300) {
+      const bodyStr =
+        typeof resp.body === "string"
+          ? resp.body
+          : JSON.stringify(resp.body ?? "");
+      if (resp.status === 410) {
+        throw new DeltaSyncExpiredError(bodyStr);
+      }
+      throw new OutlookCalendarApiError(
+        resp.status,
+        "",
+        `Microsoft Graph Calendar Delta API ${resp.status}: ${bodyStr}`,
+      );
+    }
+
+    const page = resp.body as {
+      value?: OutlookCalendarEvent[];
+      "@odata.nextLink"?: string;
+      "@odata.deltaLink"?: string;
+    };
+
+    if (page.value) {
+      allItems.push(...page.value);
+    }
+
+    newDeltaLink = page["@odata.deltaLink"];
+    currentUrl = page["@odata.nextLink"] ?? "";
+  } while (currentUrl && !newDeltaLink);
+
+  if (!newDeltaLink) {
+    throw new Error(
+      "Outlook Calendar delta query completed without returning a deltaLink",
+    );
+  }
+
+  return { items: allItems, deltaLink: newDeltaLink };
+}
+
+/**
+ * Perform the initial delta query to capture the current position.
+ * Queries calendarView/delta from now to 30 days out with the selected fields,
+ * paginating through all pages until reaching the final @odata.deltaLink.
+ */
+async function initialDeltaQuery(
+  connection: OAuthConnection,
+): Promise<DeltaSyncResult> {
+  const now = new Date();
+  const thirtyDaysOut = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);
+
+  const allItems: OutlookCalendarEvent[] = [];
+  let nextLink: string | undefined;
+  let newDeltaLink: string | undefined;
+
+  // First request — initial delta query with parameters
+  const initialQuery: Record<string, string> = {
+    startDateTime: now.toISOString(),
+    endDateTime: thirtyDaysOut.toISOString(),
+    $select: DELTA_SELECT_FIELDS,
+  };
+
+  const firstResp = await connection.request({
+    method: "GET",
+    path: "/v1.0/me/calendarView/delta",
+    query: initialQuery,
+  });
+
+  if (firstResp.status < 200 || firstResp.status >= 300) {
+    const bodyStr =
+      typeof firstResp.body === "string"
+        ? firstResp.body
+        : JSON.stringify(firstResp.body ?? "");
+    throw new OutlookCalendarApiError(
+      firstResp.status,
+      "",
+      `Microsoft Graph Calendar Delta API ${firstResp.status}: ${bodyStr}`,
+    );
+  }
+
+  const firstPage = firstResp.body as {
+    value?: OutlookCalendarEvent[];
+    "@odata.nextLink"?: string;
+    "@odata.deltaLink"?: string;
+  };
+
+  if (firstPage.value) {
+    allItems.push(...firstPage.value);
+  }
+
+  newDeltaLink = firstPage["@odata.deltaLink"];
+  nextLink = firstPage["@odata.nextLink"];
+
+  // Follow pagination until we get a deltaLink
+  while (nextLink && !newDeltaLink) {
+    const parsed = new URL(nextLink);
+    const path = parsed.pathname;
+    const query: Record<string, string> = {};
+    parsed.searchParams.forEach((v, k) => {
+      query[k] = v;
+    });
+
+    const resp = await connection.request({
+      method: "GET",
+      path,
+      query: Object.keys(query).length > 0 ? query : undefined,
+    });
+
+    if (resp.status < 200 || resp.status >= 300) {
+      const bodyStr =
+        typeof resp.body === "string"
+          ? resp.body
+          : JSON.stringify(resp.body ?? "");
+      throw new OutlookCalendarApiError(
+        resp.status,
+        "",
+        `Microsoft Graph Calendar Delta API ${resp.status}: ${bodyStr}`,
+      );
+    }
+
+    const page = resp.body as {
+      value?: OutlookCalendarEvent[];
+      "@odata.nextLink"?: string;
+      "@odata.deltaLink"?: string;
+    };
+
+    if (page.value) {
+      allItems.push(...page.value);
+    }
+
+    newDeltaLink = page["@odata.deltaLink"];
+    nextLink = page["@odata.nextLink"];
+  }
+
+  if (!newDeltaLink) {
+    throw new Error(
+      "Outlook Calendar initial delta query completed without returning a deltaLink",
+    );
+  }
+
+  return { items: allItems, deltaLink: newDeltaLink };
+}
+
+export const outlookCalendarProvider: WatcherProvider = {
+  id: "outlook-calendar",
+  displayName: "Outlook Calendar",
+  requiredCredentialService: CREDENTIAL_SERVICE,
+
+  async getInitialWatermark(credentialService: string): Promise<string> {
+    const connection = await resolveOAuthConnection(credentialService);
+    const { deltaLink } = await initialDeltaQuery(connection);
+    return deltaLink;
+  },
+
+  async fetchNew(
+    credentialService: string,
+    watermark: string | null,
+    _config: Record<string, unknown>,
+    _watcherKey: string,
+  ): Promise<FetchResult> {
+    const connection = await resolveOAuthConnection(credentialService);
+
+    if (!watermark) {
+      // No watermark — get initial position, return no items
+      const { deltaLink } = await initialDeltaQuery(connection);
+      return { items: [], watermark: deltaLink };
+    }
+
+    try {
+      const { items: events, deltaLink: newDeltaLink } = await deltaSync(
+        connection,
+        watermark,
+      );
+
+      if (events.length === 0) {
+        return { items: [], watermark: newDeltaLink };
+      }
+
+      // Filter out cancelled events and convert to watcher items
+      const items: WatcherItem[] = [];
+      for (const event of events) {
+        if (event.isCancelled) continue;
+
+        const eventType =
+          event.createdDateTime === event.lastModifiedDateTime
+            ? "new_calendar_event"
+            : "updated_calendar_event";
+        items.push(eventToItem(event, eventType));
+      }
+
+      log.info(
+        { count: items.length, watermark: newDeltaLink },
+        "Outlook Calendar: fetched event changes",
+      );
+
+      return { items, watermark: newDeltaLink };
+    } catch (err) {
+      if (err instanceof DeltaSyncExpiredError) {
+        log.warn(
+          "Outlook Calendar delta token expired, falling back to fresh query",
+        );
+        return fallbackFetch(connection);
+      }
+      throw err;
+    }
+  },
+};
+
+/**
+ * Fallback when delta token expires (410 Gone): perform a fresh initial
+ * delta query to get current events and a new deltaLink.
+ */
+async function fallbackFetch(
+  connection: OAuthConnection,
+): Promise<FetchResult> {
+  const { items: events, deltaLink } = await initialDeltaQuery(connection);
+
+  const items = events
+    .filter((event) => !event.isCancelled)
+    .map((event) => eventToItem(event, "new_calendar_event"));
+
+  return { items, watermark: deltaLink };
+}

package/src/watcher/providers/outlook.ts

@@ -0,0 +1,198 @@
+/**
+ * Outlook watcher provider — uses Microsoft Graph delta queries for efficient
+ * change detection.
+ *
+ * On first poll, captures the initial deltaLink as the watermark (start from "now").
+ * Subsequent polls use the deltaLink to detect new messages.
+ * Falls back to listing recent inbox messages if the sync state has expired (410 Gone).
+ */
+
+import {
+  listMessages,
+  listMessagesDelta,
+  OutlookApiError,
+} from "../../messaging/providers/outlook/client.js";
+import type {
+  OutlookDeltaResponse,
+  OutlookMessage,
+} from "../../messaging/providers/outlook/types.js";
+import type { OAuthConnection } from "../../oauth/connection.js";
+import { resolveOAuthConnection } from "../../oauth/connection-resolver.js";
+import { getLogger } from "../../util/logger.js";
+import type {
+  FetchResult,
+  WatcherItem,
+  WatcherProvider,
+} from "../provider-types.js";
+
+const log = getLogger("watcher:outlook");
+
+/** Thrown when Microsoft Graph returns 410 Gone (delta sync state expired). */
+export class DeltaSyncExpiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DeltaSyncExpiredError";
+  }
+}
+
+function messageToItem(msg: OutlookMessage): WatcherItem {
+  const from =
+    msg.from?.emailAddress?.name ||
+    msg.from?.emailAddress?.address ||
+    "Unknown";
+  const subject = msg.subject ?? "(no subject)";
+
+  return {
+    externalId: msg.id,
+    eventType: "new_email",
+    summary: `Email from ${from}: ${subject}`,
+    payload: {
+      id: msg.id,
+      conversationId: msg.conversationId,
+      from,
+      fromAddress: msg.from?.emailAddress?.address ?? "",
+      subject,
+      receivedDateTime: msg.receivedDateTime,
+      bodyPreview: msg.bodyPreview ?? "",
+      isRead: msg.isRead ?? false,
+      hasAttachments: msg.hasAttachments ?? false,
+    },
+    timestamp: msg.receivedDateTime
+      ? new Date(msg.receivedDateTime).getTime()
+      : Date.now(),
+  };
+}
+
+/**
+ * Fetch all pages of a delta response, following @odata.nextLink until
+ * a @odata.deltaLink is returned.
+ */
+async function fetchAllDeltaPages(
+  connection: OAuthConnection,
+  folderId: string,
+  deltaLink?: string,
+): Promise<{ messages: OutlookMessage[]; newDeltaLink: string }> {
+  const messages: OutlookMessage[] = [];
+
+  let resp: OutlookDeltaResponse<OutlookMessage>;
+  try {
+    resp = await listMessagesDelta(connection, folderId, deltaLink);
+  } catch (err) {
+    if (err instanceof OutlookApiError && err.status === 410) {
+      throw new DeltaSyncExpiredError(err.message);
+    }
+    throw err;
+  }
+
+  if (resp.value) {
+    messages.push(...resp.value);
+  }
+
+  // Follow pagination until we get a deltaLink
+  while (resp["@odata.nextLink"] && !resp["@odata.deltaLink"]) {
+    try {
+      resp = await listMessagesDelta(
+        connection,
+        folderId,
+        resp["@odata.nextLink"],
+      );
+    } catch (err) {
+      if (err instanceof OutlookApiError && err.status === 410) {
+        throw new DeltaSyncExpiredError(
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+      throw err;
+    }
+    if (resp.value) {
+      messages.push(...resp.value);
+    }
+  }
+
+  const newDeltaLink = resp["@odata.deltaLink"];
+  if (!newDeltaLink) {
+    throw new Error(
+      "Outlook delta query completed without returning a deltaLink",
+    );
+  }
+
+  return { messages, newDeltaLink };
+}
+
+export const outlookProvider: WatcherProvider = {
+  id: "outlook",
+  displayName: "Outlook",
+  requiredCredentialService: "outlook",
+
+  async getInitialWatermark(credentialService: string): Promise<string> {
+    const connection = await resolveOAuthConnection(credentialService);
+    const { newDeltaLink } = await fetchAllDeltaPages(connection, "inbox");
+    return newDeltaLink;
+  },
+
+  async fetchNew(
+    credentialService: string,
+    watermark: string | null,
+    _config: Record<string, unknown>,
+    _watcherKey: string,
+  ): Promise<FetchResult> {
+    const connection = await resolveOAuthConnection(credentialService);
+
+    if (!watermark) {
+      // No watermark — get initial position, return no items
+      const { newDeltaLink } = await fetchAllDeltaPages(connection, "inbox");
+      return { items: [], watermark: newDeltaLink };
+    }
+
+    try {
+      const { messages, newDeltaLink } = await fetchAllDeltaPages(
+        connection,
+        "inbox",
+        watermark,
+      );
+
+      if (messages.length === 0) {
+        return { items: [], watermark: newDeltaLink };
+      }
+
+      const items = messages.map(messageToItem);
+      log.info(
+        { count: items.length, watermark: newDeltaLink },
+        "Outlook: fetched new messages",
+      );
+
+      return { items, watermark: newDeltaLink };
+    } catch (err) {
+      if (err instanceof DeltaSyncExpiredError) {
+        log.warn(
+          "Outlook delta sync state expired, falling back to recent inbox messages",
+        );
+        return fallbackFetch(connection);
+      }
+      throw err;
+    }
+  },
+};
+
+/**
+ * Fallback when sync state expires (410 Gone): list recent inbox messages
+ * from the last day, then get a fresh deltaLink.
+ */
+async function fallbackFetch(
+  connection: OAuthConnection,
+): Promise<FetchResult> {
+  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+  const resp = await listMessages(connection, {
+    folderId: "inbox",
+    top: 20,
+    filter: `receivedDateTime ge ${oneDayAgo}`,
+    orderby: "receivedDateTime desc",
+  });
+
+  const items = (resp.value ?? []).map(messageToItem);
+
+  // Get a fresh deltaLink for the new watermark
+  const { newDeltaLink } = await fetchAllDeltaPages(connection, "inbox");
+
+  return { items, watermark: newDeltaLink };
+}

package/src/workspace/migrations/025-remove-oauth-app-setup-skills.ts

@@ -0,0 +1,76 @@
+/**
+ * Workspace migration 025: Remove standalone OAuth app setup skill directories
+ * and their SKILLS.md entries from user workspaces.
+ *
+ * These skills have been consolidated into vellum-oauth-integrations and are
+ * no longer shipped as standalone skills.
+ *
+ * Idempotent: safe to re-run after interruption at any point.
+ */
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Skills to remove
+// ---------------------------------------------------------------------------
+
+const DELETED_SKILLS = [
+  "airtable-oauth-app-setup",
+  "asana-oauth-app-setup",
+  "discord-oauth-app-setup",
+  "dropbox-oauth-app-setup",
+  "figma-oauth-app-setup",
+  "github-oauth-app-setup",
+  "google-oauth-app-setup",
+  "hubspot-oauth-app-setup",
+  "linear-oauth-app-setup",
+  "notion-oauth-app-setup",
+  "spotify-oauth-app-setup",
+  "todoist-oauth-app-setup",
+  "twitter-oauth-app-setup",
+];
+
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+
+export const removeOauthAppSetupSkillsMigration: WorkspaceMigration = {
+  id: "025-remove-oauth-app-setup-skills",
+  description:
+    "Remove standalone OAuth app setup skill directories consolidated into vellum-oauth-integrations",
+
+  run(workspaceDir: string): void {
+    const skillsDir = join(workspaceDir, "skills");
+    if (!existsSync(skillsDir)) return;
+
+    // 1. Remove skill directories
+    for (const name of DELETED_SKILLS) {
+      const dir = join(skillsDir, name);
+      if (existsSync(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    }
+
+    // 2. Update SKILLS.md to remove entries referencing deleted skills
+    const indexPath = join(skillsDir, "SKILLS.md");
+    if (existsSync(indexPath)) {
+      let content = readFileSync(indexPath, "utf-8");
+      for (const name of DELETED_SKILLS) {
+        content = content.replace(
+          new RegExp(`^[\\t ]*-\\s*${name}\\s*\\n?`, "gm"),
+          "",
+        );
+      }
+      writeFileSync(indexPath, content, "utf-8");
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Deleted skills cannot be restored since they have been removed from the
+    // repo. Users would need to reinstall the `vellum-oauth-integrations`
+    // skill to regain the consolidated OAuth setup functionality.
+  },
+};