@vellumai/assistant 0.5.16 → 0.6.1

package/src/config/bundled-skills/outlook-calendar/TOOLS.json

@@ -0,0 +1,221 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "outlook_calendar_list_events",
+      "description": "List upcoming Outlook Calendar events within a date range. Returns event summaries, times, and metadata.",
+      "category": "calendar",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID to query. If omitted, uses the default calendar."
+          },
+          "time_min": {
+            "type": "string",
+            "description": "Start of time range in ISO 8601 format (e.g. \"2024-01-15T00:00:00Z\"). Defaults to now."
+          },
+          "time_max": {
+            "type": "string",
+            "description": "End of time range in ISO 8601 format (e.g. \"2024-01-22T00:00:00Z\"). Defaults to 7 days from now."
+          },
+          "max_results": {
+            "type": "number",
+            "description": "Maximum number of events to return (default 25, max 250)"
+          },
+          "query": {
+            "type": "string",
+            "description": "OData $filter expression to filter events"
+          },
+          "order_by": {
+            "type": "string",
+            "description": "OData $orderby expression (default \"start/dateTime\")"
+          },
+          "account": {
+            "type": "string",
+            "description": "Email address of the Outlook account to use. Required when multiple Outlook accounts are connected. If omitted, uses the most recently connected account."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/outlook-calendar-list-events.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "outlook_calendar_get_event",
+      "description": "Get the full details of a single Outlook Calendar event by its ID.",
+      "category": "calendar",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "event_id": {
+            "type": "string",
+            "description": "The Outlook Calendar event ID"
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID. If omitted, uses the default calendar."
+          },
+          "account": {
+            "type": "string",
+            "description": "Email address of the Outlook account to use. Required when multiple Outlook accounts are connected. If omitted, uses the most recently connected account."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["event_id"]
+      },
+      "executor": "tools/outlook-calendar-get-event.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "outlook_calendar_create_event",
+      "description": "Create a new Outlook Calendar event. Include a confidence score (0-1) indicating how certain you are this action is correct.",
+      "category": "calendar",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "summary": {
+            "type": "string",
+            "description": "Event title (maps to the Outlook subject field)"
+          },
+          "start": {
+            "type": "string",
+            "description": "Start time in ISO 8601 format (e.g. \"2024-01-15T09:00:00-05:00\") or date for all-day events (\"2024-01-15\")"
+          },
+          "end": {
+            "type": "string",
+            "description": "End time in ISO 8601 format or date for all-day events"
+          },
+          "description": {
+            "type": "string",
+            "description": "Event description or notes"
+          },
+          "location": {
+            "type": "string",
+            "description": "Event location"
+          },
+          "attendees": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Email addresses of attendees to invite"
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone (e.g. \"America/New_York\"). Required when start/end don't include timezone offset."
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID. If omitted, uses the default calendar."
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "account": {
+            "type": "string",
+            "description": "Email address of the Outlook account to use. Required when multiple Outlook accounts are connected. If omitted, uses the most recently connected account."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["summary", "start", "end", "confidence"]
+      },
+      "executor": "tools/outlook-calendar-create-event.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "outlook_calendar_check_availability",
+      "description": "Check free/busy status across one or more schedules to find available time slots.",
+      "category": "calendar",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "time_min": {
+            "type": "string",
+            "description": "Start of time range in ISO 8601 format"
+          },
+          "time_max": {
+            "type": "string",
+            "description": "End of time range in ISO 8601 format"
+          },
+          "schedules": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Email addresses of schedules to check. Defaults to the authenticated user."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone for interpreting results (e.g. \"America/New_York\")"
+          },
+          "account": {
+            "type": "string",
+            "description": "Email address of the Outlook account to use. Required when multiple Outlook accounts are connected. If omitted, uses the most recently connected account."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["time_min", "time_max"]
+      },
+      "executor": "tools/outlook-calendar-check-availability.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "outlook_calendar_rsvp",
+      "description": "Respond to an Outlook Calendar event invitation (accept, decline, or tentative). Include a confidence score (0-1).",
+      "category": "calendar",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "event_id": {
+            "type": "string",
+            "description": "The Outlook Calendar event ID"
+          },
+          "response": {
+            "type": "string",
+            "enum": ["accepted", "declined", "tentative"],
+            "description": "RSVP response"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID. If omitted, uses the default calendar."
+          },
+          "account": {
+            "type": "string",
+            "description": "Email address of the Outlook account to use. Required when multiple Outlook accounts are connected. If omitted, uses the most recently connected account."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["event_id", "response", "confidence"]
+      },
+      "executor": "tools/outlook-calendar-rsvp.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/outlook-calendar/calendar-client.ts

@@ -0,0 +1,252 @@
+import type {
+  OAuthConnection,
+  OAuthConnectionResponse,
+} from "../../../oauth/connection.js";
+import type {
+  OutlookCalendarEvent,
+  OutlookCalendarEventListResponse,
+  OutlookCalendarListResponse,
+  OutlookDateTimeZone,
+  OutlookScheduleResponse,
+} from "./types.js";
+
+export class OutlookCalendarApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "OutlookCalendarApiError";
+  }
+}
+
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 1000;
+
+function isRetryable(status: number): boolean {
+  return status === 429 || (status >= 500 && status < 600);
+}
+
+const IDEMPOTENT_METHODS = new Set([
+  "GET",
+  "HEAD",
+  "PUT",
+  "DELETE",
+  "OPTIONS",
+  "PATCH",
+]);
+
+function isIdempotent(method: string): boolean {
+  return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+
+/**
+ * Make an authenticated request to the Microsoft Graph API with retry logic.
+ *
+ * The OAuth provider's baseUrl is `https://graph.microsoft.com`, so all paths
+ * must include the full API version and resource prefix (e.g. `/v1.0/me/events`).
+ */
+async function request<T>(
+  connection: OAuthConnection,
+  path: string,
+  options?: RequestInit,
+  query?: Record<string, string | string[]>,
+): Promise<T> {
+  const method = (options?.method ?? "GET").toUpperCase();
+  const canRetry = isIdempotent(method);
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    let resp: OAuthConnectionResponse;
+    try {
+      const extraHeaders =
+        options?.headers &&
+        typeof options.headers === "object" &&
+        !Array.isArray(options.headers)
+          ? (options.headers as Record<string, string>)
+          : {};
+      resp = await connection.request({
+        method,
+        path,
+        query,
+        headers: {
+          "Content-Type": "application/json",
+          ...extraHeaders,
+        },
+        body: options?.body ? JSON.parse(options.body as string) : undefined,
+      });
+    } catch (err) {
+      // Network-level errors from connection.request() are not retryable
+      throw err;
+    }
+
+    if (resp.status < 200 || resp.status >= 300) {
+      if (canRetry && isRetryable(resp.status) && attempt < MAX_RETRIES) {
+        const retryAfter =
+          resp.headers["retry-after"] ?? resp.headers["Retry-After"];
+        const delayMs = retryAfter
+          ? parseInt(retryAfter, 10) * 1000
+          : INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        continue;
+      }
+      const bodyStr =
+        typeof resp.body === "string"
+          ? resp.body
+          : JSON.stringify(resp.body ?? "");
+      throw new OutlookCalendarApiError(
+        resp.status,
+        "",
+        `Microsoft Graph API ${resp.status}: ${bodyStr}`,
+      );
+    }
+
+    // Success
+    if (resp.status === 204 || resp.body === undefined) {
+      return undefined as T;
+    }
+    return resp.body as T;
+  }
+
+  throw new Error(
+    "Unreachable: retry loop exited without returning or throwing",
+  );
+}
+
+/** List calendar events, optionally within a specific calendar. */
+export async function listEvents(
+  connection: OAuthConnection,
+  calendarId?: string,
+  options?: {
+    top?: number;
+    skip?: number;
+    filter?: string;
+    orderby?: string;
+    select?: string;
+  },
+): Promise<OutlookCalendarEventListResponse> {
+  const path =
+    calendarId && calendarId !== "primary"
+      ? `/v1.0/me/calendars/${encodeURIComponent(calendarId)}/events`
+      : "/v1.0/me/events";
+
+  const query: Record<string, string> = {};
+  if (options?.top !== undefined) query["$top"] = String(options.top);
+  if (options?.skip !== undefined) query["$skip"] = String(options.skip);
+  if (options?.filter) query["$filter"] = options.filter;
+  query["$orderby"] = options?.orderby ?? "start/dateTime";
+  if (options?.select) query["$select"] = options.select;
+
+  return request<OutlookCalendarEventListResponse>(
+    connection,
+    path,
+    undefined,
+    Object.keys(query).length > 0 ? query : undefined,
+  );
+}
+
+/** Get a single calendar event by ID. */
+export async function getEvent(
+  connection: OAuthConnection,
+  eventId: string,
+  select?: string,
+): Promise<OutlookCalendarEvent> {
+  const query: Record<string, string> = {};
+  if (select) query["$select"] = select;
+
+  return request<OutlookCalendarEvent>(
+    connection,
+    `/v1.0/me/events/${encodeURIComponent(eventId)}`,
+    undefined,
+    Object.keys(query).length > 0 ? query : undefined,
+  );
+}
+
+/** Create a new calendar event. */
+export async function createEvent(
+  connection: OAuthConnection,
+  event: Partial<OutlookCalendarEvent>,
+  calendarId?: string,
+): Promise<OutlookCalendarEvent> {
+  const path =
+    calendarId && calendarId !== "primary"
+      ? `/v1.0/me/calendars/${encodeURIComponent(calendarId)}/events`
+      : "/v1.0/me/events";
+
+  return request<OutlookCalendarEvent>(connection, path, {
+    method: "POST",
+    body: JSON.stringify(event),
+  });
+}
+
+/** Update (patch) an existing calendar event. */
+export async function patchEvent(
+  connection: OAuthConnection,
+  eventId: string,
+  updates: Partial<OutlookCalendarEvent>,
+): Promise<OutlookCalendarEvent> {
+  return request<OutlookCalendarEvent>(
+    connection,
+    `/v1.0/me/events/${encodeURIComponent(eventId)}`,
+    {
+      method: "PATCH",
+      body: JSON.stringify(updates),
+    },
+  );
+}
+
+/** RSVP to a calendar event (accept, decline, or tentatively accept). */
+export async function rsvpEvent(
+  connection: OAuthConnection,
+  eventId: string,
+  response: "accepted" | "declined" | "tentative",
+  sendResponse?: boolean,
+  comment?: string,
+): Promise<void> {
+  const endpointMap: Record<string, string> = {
+    accepted: "accept",
+    declined: "decline",
+    tentative: "tentativelyAccept",
+  };
+
+  const action = endpointMap[response];
+  const body: Record<string, unknown> = {};
+  if (sendResponse !== undefined) body.sendResponse = sendResponse;
+  if (comment !== undefined) body.comment = comment;
+
+  await request<void>(
+    connection,
+    `/v1.0/me/events/${encodeURIComponent(eventId)}/${action}`,
+    {
+      method: "POST",
+      body: JSON.stringify(body),
+    },
+  );
+}
+
+/** Get free/busy schedule for one or more users by email address. */
+export async function getSchedule(
+  connection: OAuthConnection,
+  query: {
+    schedules: string[];
+    startTime: OutlookDateTimeZone;
+    endTime: OutlookDateTimeZone;
+    availabilityViewInterval?: number;
+  },
+): Promise<OutlookScheduleResponse> {
+  return request<OutlookScheduleResponse>(
+    connection,
+    "/v1.0/me/calendar/getSchedule",
+    {
+      method: "POST",
+      body: JSON.stringify(query),
+    },
+  );
+}
+
+/** List all calendars in the user's mailbox. */
+export async function listCalendars(
+  connection: OAuthConnection,
+): Promise<OutlookCalendarListResponse> {
+  return request<OutlookCalendarListResponse>(connection, "/v1.0/me/calendars");
+}

package/src/config/bundled-skills/outlook-calendar/tools/outlook-calendar-check-availability.ts

@@ -0,0 +1,53 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import * as calendar from "../calendar-client.js";
+import { err, getCalendarConnection, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const timeMin = input.time_min as string;
+  const timeMax = input.time_max as string;
+  let schedules = (input.schedules as string[] | undefined) ?? [];
+  const timezone = (input.timezone as string | undefined) ?? "UTC";
+
+  const connection = await getCalendarConnection(account);
+
+  if (schedules.length === 0) {
+    const resp = await connection.request({
+      method: "GET",
+      path: "/v1.0/me",
+    });
+    if (resp.status < 200 || resp.status >= 300) {
+      return err(
+        "Failed to retrieve your Microsoft profile. Cannot determine your email for availability lookup.",
+      );
+    }
+    const body = resp.body as Record<string, unknown>;
+    const email =
+      (body.mail as string | undefined) ??
+      (body.userPrincipalName as string | undefined);
+    if (email) {
+      schedules = [email];
+    }
+  }
+
+  if (schedules.length === 0) {
+    return err(
+      "No schedules provided and could not determine your email address from your Microsoft profile. " +
+        "Please provide at least one email address in the schedules parameter.",
+    );
+  }
+
+  const result = await calendar.getSchedule(connection, {
+    schedules,
+    startTime: { dateTime: timeMin, timeZone: timezone },
+    endTime: { dateTime: timeMax, timeZone: timezone },
+  });
+
+  return ok(JSON.stringify(result, null, 2));
+}

package/src/config/bundled-skills/outlook-calendar/tools/outlook-calendar-create-event.ts

@@ -0,0 +1,74 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import * as calendar from "../calendar-client.js";
+import { getCalendarConnection, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const summary = input.summary as string;
+  const startRaw = input.start as string;
+  const endRaw = input.end as string;
+  const description = input.description as string | undefined;
+  const location = input.location as string | undefined;
+  const attendees = input.attendees as string[] | undefined;
+  const timezone = input.timezone as string | undefined;
+  const calendarId = input.calendar_id as string | undefined;
+
+  // Detect all-day events: if start string does not contain "T", treat as all-day
+  const isAllDay = !startRaw.includes("T");
+
+  // Determine the timeZone to send. If the caller provided an explicit IANA
+  // timezone, always use it.  Otherwise, only fall back to UTC when the
+  // dateTime string does NOT already carry an offset (e.g. "-05:00" or "Z").
+  // Sending timeZone: "UTC" alongside a dateTime that contains a different
+  // offset would cause Microsoft Graph to ignore the offset and interpret the
+  // time as UTC, creating events at the wrong wall-clock time.
+  const hasOffset = (dt: string) => /[Zz]|[+-]\d{2}:\d{2}$/.test(dt);
+  const resolveTimeZone = (dt: string) =>
+    timezone ?? (hasOffset(dt) ? undefined : "UTC");
+
+  const start = isAllDay
+    ? {
+        dateTime: `${startRaw}T00:00:00`,
+        timeZone: timezone ?? "UTC",
+      }
+    : { dateTime: startRaw, timeZone: resolveTimeZone(startRaw) };
+
+  const end = isAllDay
+    ? {
+        dateTime: `${endRaw}T00:00:00`,
+        timeZone: timezone ?? "UTC",
+      }
+    : { dateTime: endRaw, timeZone: resolveTimeZone(endRaw) };
+
+  const eventBody: Parameters<typeof calendar.createEvent>[1] = {
+    subject: summary,
+    start,
+    end,
+    isAllDay,
+  };
+
+  if (description) {
+    eventBody.body = { contentType: "text", content: description };
+  }
+  if (location) {
+    eventBody.location = { displayName: location };
+  }
+  if (attendees?.length) {
+    eventBody.attendees = attendees.map((email) => ({
+      emailAddress: { address: email },
+      type: "required" as const,
+    }));
+  }
+
+  const connection = await getCalendarConnection(account);
+  const event = await calendar.createEvent(connection, eventBody, calendarId);
+  return ok(
+    `Event created (ID: ${event.id}).${event.webLink ? ` View it here: ${event.webLink}` : ""}`,
+  );
+}

package/src/config/bundled-skills/outlook-calendar/tools/outlook-calendar-get-event.ts

@@ -0,0 +1,18 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import * as calendar from "../calendar-client.js";
+import { getCalendarConnection, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const eventId = input.event_id as string;
+
+  const connection = await getCalendarConnection(account);
+  const event = await calendar.getEvent(connection, eventId);
+  return ok(JSON.stringify(event, null, 2));
+}

package/src/config/bundled-skills/outlook-calendar/tools/outlook-calendar-list-events.ts

@@ -0,0 +1,46 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import * as calendar from "../calendar-client.js";
+import { getCalendarConnection, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const account = input.account as string | undefined;
+  const calendarId = input.calendar_id as string | undefined;
+  const timeMin = (input.time_min as string) ?? new Date().toISOString();
+  const timeMax = input.time_max as string | undefined;
+  const maxResults = Math.min((input.max_results as number) ?? 25, 250);
+  const query = input.query as string | undefined;
+  const orderBy = input.order_by as string | undefined;
+
+  const connection = await getCalendarConnection(account);
+
+  // Build OData $filter from time range and optional user query
+  const filterParts: string[] = [];
+  if (timeMin) {
+    filterParts.push(`start/dateTime ge '${timeMin}'`);
+  }
+  if (timeMax) {
+    filterParts.push(`start/dateTime le '${timeMax}'`);
+  }
+  if (query) {
+    filterParts.push(query);
+  }
+  const filter = filterParts.length > 0 ? filterParts.join(" and ") : undefined;
+
+  const result = await calendar.listEvents(connection, calendarId, {
+    filter,
+    top: maxResults,
+    orderby: orderBy,
+  });
+
+  if (!result.value?.length) {
+    return ok("No events found in the specified time range.");
+  }
+
+  return ok(JSON.stringify(result, null, 2));
+}