@vellumai/assistant 0.4.43 → 0.4.45

package/src/config/bundled-skills/gmail/TOOLS.json

@@ -0,0 +1,506 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "gmail_archive",
+      "description": "Archive Gmail messages (remove from inbox). Accepts a single message_id, an array of message_ids, scan_id + sender_ids from a prior scan, or a query to archive all matches. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID to archive"
+          },
+          "message_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Gmail message IDs to archive (for batch operations)"
+          },
+          "scan_id": {
+            "type": "string",
+            "description": "Scan result ID from a prior gmail_sender_digest or gmail_outreach_scan call"
+          },
+          "sender_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sender IDs to archive (used with scan_id)"
+          },
+          "query": {
+            "type": "string",
+            "description": "Gmail search query to archive all matching messages"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["confidence"]
+      },
+      "executor": "tools/gmail-archive.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_label",
+      "description": "Add or remove labels on one or more Gmail messages. Accepts a single message_id or an array of message_ids. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID"
+          },
+          "message_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Gmail message IDs for batch label operations"
+          },
+          "add_label_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Label IDs to add"
+          },
+          "remove_label_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Label IDs to remove"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["confidence"]
+      },
+      "executor": "tools/gmail-label.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_trash",
+      "description": "Move a Gmail message to trash. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID to trash"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["message_id", "confidence"]
+      },
+      "executor": "tools/gmail-trash.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_unsubscribe",
+      "description": "Unsubscribe from a mailing list by following the List-Unsubscribe header. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "description": "A Gmail message ID from the mailing list to unsubscribe from"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["message_id", "confidence"]
+      },
+      "executor": "tools/gmail-unsubscribe.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_draft",
+      "description": "Create a draft email in Gmail. The draft will appear in Gmail Drafts for user review.",
+      "category": "gmail",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "to": {
+            "type": "string",
+            "description": "Recipient email address"
+          },
+          "subject": {
+            "type": "string",
+            "description": "Email subject line"
+          },
+          "body": {
+            "type": "string",
+            "description": "Email body (plain text)"
+          },
+          "in_reply_to": {
+            "type": "string",
+            "description": "RFC 822 Message-ID header value (e.g. `<CABx...@mail.gmail.com>`), NOT the Gmail message ID. Look up the original message's Message-ID header."
+          },
+          "cc": {
+            "type": "string",
+            "description": "CC recipients (comma-separated email addresses)"
+          },
+          "bcc": {
+            "type": "string",
+            "description": "BCC recipients (comma-separated email addresses)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["to", "subject", "body"]
+      },
+      "executor": "tools/gmail-draft.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_send_draft",
+      "description": "Send an existing Gmail draft. Only use when the user has reviewed and explicitly approved sending.",
+      "category": "gmail",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "draft_id": {
+            "type": "string",
+            "description": "Gmail draft ID to send"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["draft_id", "confidence"]
+      },
+      "executor": "tools/gmail-send-draft.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_attachments",
+      "description": "List or download Gmail attachments. Use action 'list' to enumerate attachments on a message, then 'download' to save a specific attachment to disk.",
+      "category": "gmail",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["list", "download"],
+            "description": "List attachments on a message, or download a specific attachment"
+          },
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID"
+          },
+          "attachment_id": {
+            "type": "string",
+            "description": "Attachment ID (required for download, from a prior list call)"
+          },
+          "filename": {
+            "type": "string",
+            "description": "Filename to save as (required for download)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action", "message_id"]
+      },
+      "executor": "tools/gmail-attachments.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_forward",
+      "description": "Create a draft forwarding a Gmail message to another recipient, preserving attachments. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID to forward"
+          },
+          "to": {
+            "type": "string",
+            "description": "Recipient email address"
+          },
+          "text": {
+            "type": "string",
+            "description": "Optional text to prepend to the forwarded message"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["message_id", "to", "confidence"]
+      },
+      "executor": "tools/gmail-forward.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_follow_up",
+      "description": "Track, list, or untrack Gmail messages for follow-up using a dedicated label. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["track", "list", "untrack"],
+            "description": "Follow-up action"
+          },
+          "message_id": {
+            "type": "string",
+            "description": "Gmail message ID (required for track/untrack)"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action", "confidence"]
+      },
+      "executor": "tools/gmail-follow-up.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_filters",
+      "description": "List, create, or delete Gmail filters for inbox automation. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["list", "create", "delete"],
+            "description": "Filter action"
+          },
+          "from": {
+            "type": "string",
+            "description": "Filter criteria: sender (for create)"
+          },
+          "to": {
+            "type": "string",
+            "description": "Filter criteria: recipient (for create)"
+          },
+          "subject": {
+            "type": "string",
+            "description": "Filter criteria: subject contains (for create)"
+          },
+          "query": {
+            "type": "string",
+            "description": "Filter criteria: Gmail query (for create)"
+          },
+          "has_attachment": {
+            "type": "boolean",
+            "description": "Filter criteria: has attachment (for create)"
+          },
+          "add_label_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter action: label IDs to add (for create)"
+          },
+          "remove_label_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter action: label IDs to remove (for create)"
+          },
+          "forward": {
+            "type": "string",
+            "description": "Filter action: forward to email (for create)"
+          },
+          "filter_id": {
+            "type": "string",
+            "description": "Filter ID (for delete)"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action", "confidence"]
+      },
+      "executor": "tools/gmail-filters.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_vacation",
+      "description": "Get, enable, or disable Gmail vacation auto-responder. Include a confidence score (0-1).",
+      "category": "gmail",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["get", "enable", "disable"],
+            "description": "Vacation action"
+          },
+          "message": {
+            "type": "string",
+            "description": "Auto-reply message body (required for enable)"
+          },
+          "subject": {
+            "type": "string",
+            "description": "Auto-reply subject (default 'Out of Office')"
+          },
+          "start_time": {
+            "type": "number",
+            "description": "Start time in epoch milliseconds"
+          },
+          "end_time": {
+            "type": "number",
+            "description": "End time in epoch milliseconds"
+          },
+          "restrict_to_contacts": {
+            "type": "boolean",
+            "description": "Only auto-reply to contacts (default false)"
+          },
+          "restrict_to_domain": {
+            "type": "boolean",
+            "description": "Only auto-reply to same domain (default false)"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action", "confidence"]
+      },
+      "executor": "tools/gmail-vacation.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_sender_digest",
+      "description": "Scan Gmail and group messages by sender to identify high-volume senders (e.g. newsletters). Returns top senders sorted by message count with metadata for bulk cleanup.",
+      "category": "gmail",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Gmail search query (default 'category:promotions newer_than:90d')"
+          },
+          "max_messages": {
+            "type": "number",
+            "description": "Maximum messages to scan (default 5000, cap 10000)"
+          },
+          "max_senders": {
+            "type": "number",
+            "description": "Maximum senders to return (default 50)"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Resume token from a previous scan (rarely needed — scans now cover up to 10,000 messages in a single call)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/gmail-sender-digest.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "gmail_outreach_scan",
+      "description": "Scan Gmail inbox for senders without List-Unsubscribe headers (potential cold outreach). Returns top senders with message counts and sample subjects. Read-only — use gmail_archive and gmail_filters for cleanup.",
+      "category": "gmail",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "max_messages": {
+            "type": "number",
+            "description": "Maximum messages to scan (default 2000, cap 5000)"
+          },
+          "max_senders": {
+            "type": "number",
+            "description": "Maximum senders to return (default 30)"
+          },
+          "time_range": {
+            "type": "string",
+            "description": "Gmail time range filter (default '90d')"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Resume token from a previous scan (rarely needed — scans now cover up to 5,000 messages in a single call)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/gmail-outreach-scan.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/gmail/tools/gmail-archive.ts

@@ -0,0 +1,149 @@
+import {
+  batchModifyMessages,
+  listMessages,
+  modifyMessage,
+} from "../../../../messaging/providers/gmail/client.js";
+import { getMessagingProvider } from "../../../../messaging/registry.js";
+import { withValidToken } from "../../../../security/token-manager.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { getSenderMessageIds } from "./scan-result-store.js";
+import { err, ok } from "./shared.js";
+
+const BATCH_MODIFY_LIMIT = 1000;
+const MAX_MESSAGES = 5000;
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const query = input.query as string | undefined;
+  const scanId = input.scan_id as string | undefined;
+  const senderIds = input.sender_ids as string[] | undefined;
+  let messageIds = input.message_ids as string[] | undefined;
+  const messageId = input.message_id as string | undefined;
+
+  // Resolve message IDs via priority: query → scan_id+sender_ids → message_ids → message_id
+  if (query) {
+    // Query path requires surface action confirmation
+    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.",
+      );
+    }
+
+    try {
+      const provider = getMessagingProvider("gmail");
+      return await withValidToken(provider.credentialService, async (token) => {
+        const allMessageIds: string[] = [];
+        let pageToken: string | undefined;
+        let truncated = false;
+
+        while (allMessageIds.length < MAX_MESSAGES) {
+          const listResp = await listMessages(
+            token,
+            query,
+            Math.min(500, MAX_MESSAGES - allMessageIds.length),
+            pageToken,
+          );
+          const ids = (listResp.messages ?? []).map((m) => m.id);
+          if (ids.length === 0) break;
+          allMessageIds.push(...ids);
+          pageToken = listResp.nextPageToken ?? undefined;
+          if (!pageToken) break;
+        }
+
+        if (allMessageIds.length >= MAX_MESSAGES && pageToken) {
+          truncated = true;
+        }
+
+        if (allMessageIds.length === 0) {
+          return ok("No messages matched the query. Nothing archived.");
+        }
+
+        for (let i = 0; i < allMessageIds.length; i += BATCH_MODIFY_LIMIT) {
+          const chunk = allMessageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+          await batchModifyMessages(token, chunk, {
+            removeLabelIds: ["INBOX"],
+          });
+        }
+
+        const summary = `Archived ${allMessageIds.length} message(s) matching query: ${query}`;
+        if (truncated) {
+          return ok(
+            `${summary}\n\nNote: this operation was capped at ${MAX_MESSAGES} messages. Additional messages matching the query may remain in the inbox. Run the command again to archive more.`,
+          );
+        }
+        return ok(summary);
+      });
+    } catch (e) {
+      return err(e instanceof Error ? e.message : String(e));
+    }
+  } else if (scanId && senderIds?.length) {
+    // Scan path requires surface action confirmation
+    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 resolved = getSenderMessageIds(scanId, senderIds);
+    if (!resolved) {
+      return err(
+        "Scan results have expired (30-minute window). Please re-run the scan to get fresh results.",
+      );
+    }
+    messageIds = resolved;
+  } else if (messageIds?.length) {
+    // Batch message_ids path requires surface action confirmation
+    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.",
+      );
+    }
+  } else if (messageId) {
+    // Single message path
+    try {
+      const provider = getMessagingProvider("gmail");
+      return await withValidToken(provider.credentialService, async (token) => {
+        await modifyMessage(token, messageId, { removeLabelIds: ["INBOX"] });
+        return ok("Message archived.");
+      });
+    } catch (e) {
+      return err(e instanceof Error ? e.message : String(e));
+    }
+  } else {
+    return err(
+      "Provide message_id, message_ids, scan_id + sender_ids, or query.",
+    );
+  }
+
+  // Batch path for scan_id+sender_ids and message_ids
+  if (!messageIds?.length) {
+    return err("Resolved message list is empty — no messages to archive.");
+  }
+
+  try {
+    const provider = getMessagingProvider("gmail");
+    return await withValidToken(provider.credentialService, async (token) => {
+      if (messageIds.length === 1) {
+        await modifyMessage(token, messageIds[0], {
+          removeLabelIds: ["INBOX"],
+        });
+        return ok("Message archived.");
+      }
+
+      for (let i = 0; i < messageIds.length; i += BATCH_MODIFY_LIMIT) {
+        const chunk = messageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+        await batchModifyMessages(token, chunk, {
+          removeLabelIds: ["INBOX"],
+        });
+      }
+      return ok(`Archived ${messageIds.length} message(s).`);
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}