@vellumai/assistant 0.6.3 → 0.6.4

package/src/config/bundled-skills/gmail/SKILL.md

@@ -12,9 +12,9 @@ This skill provides Gmail-specific tools. For cross-platform messaging (send, re
 
 ## Email Routing Priority
 
-When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's @vellum.me address.
 
-Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup - do not suggest AgentMail as an alternative.
+Do not offer the assistant's own email as an option unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup.
 
 ## Communication Style
 
@@ -106,7 +106,7 @@ When searching Gmail, the query uses Gmail's search operators:
 
 When a user asks to declutter, clean up, or organize their email - start scanning immediately. Don't ask what kind of cleanup they want or request permission to read their inbox. Go straight to scanning - but once results are ready, always show them via `ui_show` and let the user choose actions before archiving or unsubscribing.
 
-**CRITICAL**: Never call `gmail_archive`, `gmail_unsubscribe`, or `messaging_archive_by_sender` unless the user has clicked an action button on the table for that specific batch. Each batch of results requires its own explicit user confirmation via the table UI. If the user says "keep going" or "keep decluttering," that means scan and present a new table - NOT auto-archive. Previous batch approvals do not carry forward, but **deselections DO carry forward**: when the user deselects senders from a cleanup table, the system records those deselections as user preferences. Before building the next cleanup table, check `<dynamic-user-profile>` for previously deselected senders and exclude them from future cleanup tables - the user already indicated they want to keep those.
+**CRITICAL**: Never call `gmail_archive`, `gmail_unsubscribe`, or `messaging_archive_by_sender` unless the user has clicked an action button on the table for that specific batch. Each batch of results requires its own explicit user confirmation via the table UI. If the user says "keep going" or "keep decluttering," that means scan and present a new table - NOT auto-archive. Previous batch approvals do not carry forward, but **deselections DO carry forward**: when the user deselects senders from a cleanup table, call `gmail_preferences` with `action: "add_safelist"` to persist those senders. Before building the next cleanup table, call `gmail_preferences` with `action: "list"` and exclude safelisted senders from the table — the user already indicated they want to keep those.
 
 ### Workflow
 
@@ -135,19 +135,65 @@ When a user asks to declutter, clean up, or organize their email - start scannin
    - If yes, call `gmail_filters` with `action: "create"` for each sender with `from` set to the sender's email and `remove_label_ids: ["INBOX"]`.
    - Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?" If yes, use `schedule_create` to set up a monthly declutter check.
 
+### Cold Outreach Cleanup
+
+After the newsletter/promotions pass, offer to clean up cold outreach — unsolicited emails from senders without unsubscribe links. This catches sales pitches, recruiting spam, and mass outreach that newsletter filters miss.
+
+1. **Scan**: Call `gmail_outreach_scan` (default: last 90 days, senders without `List-Unsubscribe` headers). The scan includes a `has_prior_reply` flag per sender — true means the user has previously replied to that sender.
+2. **Filter out known contacts**: Exclude senders where `has_prior_reply: true` — these are conversations, not cold outreach. If the `contacts` skill is loaded, also cross-reference against Google Contacts and exclude matches.
+3. **Classify senders** using sample subjects, email domains, and message patterns. Categorize into:
+   - **Clear junk** (pre-select for archive): loan/LOC offers, generic SaaS pitches, mass marketing from unknown domains, senders with random/concatenated domain names
+   - **Sales outreach** (pre-select for archive): targeted product pitches with personalised subject lines ("Hi [name]", "for [company]"), outreach tool domains (apollo.io, outreach.io, lemlist.com, instantly.ai, etc.)
+   - **Potentially useful** (deselect / keep by default): recruiting, investor outreach, partnership proposals, vendor introductions that reference the user's specific product or role
+   - **Ambiguous** (deselect / keep by default): anything you're not confident about
+4. **Present as a table** following the same `ui_show` pattern as the newsletter workflow. Use two visual sections:
+   - Pre-selected rows: clear junk + sales outreach
+   - Deselected rows: potentially useful + ambiguous senders (user reviews these)
+   - **Caption**: "Cold outreach from the last 90 days (senders without unsubscribe links). Pre-selected senders look like spam or sales pitches. Deselected senders may be useful — review before archiving."
+5. **Archive on user action**: Same flow as newsletter cleanup — wait for surface action button click, then batch archive.
+
+**Key principle**: Not all cold outreach is unwanted. Recruiting, investor, and partnership emails can be valuable. When uncertain, default to keeping the sender (deselected) and let the user decide.
+
+### Large Inbox Handling
+
+When a scan returns `truncated: true` or `time_budget_exceeded: true`, the inbox has more messages than a single scan pass can cover. Split subsequent scans by date range to ensure full coverage:
+
+```
+Pass 1: in:inbox older_than:90d                     (oldest backlog)
+Pass 2: in:inbox newer_than:90d older_than:30d      (recent months)
+Pass 3: in:inbox newer_than:30d older_than:7d       (recent weeks)
+Pass 4: in:inbox newer_than:7d                      (this week)
+```
+
+Merge results from all passes before presenting the final table. Each pass covers a smaller window, reducing per-scan message count and avoiding timeouts. Only split when a scan actually reports truncation — most inboxes are handled fine in a single pass.
+
 ### Edge Cases
 
 - **Zero results**: Tell the user "No newsletter emails found" and suggest broadening the query (e.g. removing the category filter or extending the date range)
 - **Unsubscribe failures**: Report per-sender success/failure; the existing `gmail_unsubscribe` tool handles edge cases
-- **Truncation handling**: The scan covers up to 5,000 messages by default (cap 10,000). If `truncated` is true, the top senders are still captured - don't offer to scan more. Tell the user: "Scanned [N] messages - here are your top senders."
-- **Time budget exceeded**: If the scan returns `time_budget_exceeded: true`, present whatever results were collected. Do not retry or continue - the partial results are useful as-is.
+- **Truncation handling**: The scan covers up to 5,000 messages by default (cap 10,000). If `truncated` is true, the top senders are still captured. Offer to run additional date-range passes to cover the remaining messages (see Large Inbox Handling above).
+- **Time budget exceeded**: If the scan returns `time_budget_exceeded: true`, present whatever results were collected. Offer to run additional date-range passes for uncovered periods.
+
+## Cleanup Preferences (Blocklist & Safelist)
+
+The `gmail_preferences` tool persists sender preferences across cleanup sessions:
+
+- **Blocklist**: Sender emails archived in previous sessions. On future cleanups, pre-pass archive all blocklisted senders before scanning (use `gmail_archive` with `query: "from:email1 OR from:email2 ... in:inbox"`).
+- **Safelist**: Sender emails the user explicitly deselected (chose to keep). Exclude these senders from future cleanup tables entirely.
+
+### Workflow integration
+
+1. **Before scanning**: Call `gmail_preferences` with `action: "list"`. If blocklisted senders exist, offer to auto-archive them first ("I have N previously archived senders — want me to clean those up first?"). Remove safelisted senders from scan results before presenting the table.
+2. **After archiving**: The blocklist is updated automatically when `gmail_archive` runs with `scan_id` + `sender_ids`.
+3. **After user deselects**: When the user deselects senders from a cleanup table, call `gmail_preferences` with `action: "add_safelist"` and the deselected sender emails.
+4. **User overrides**: If the user asks to stop blocking or stop keeping a sender, use `remove_blocklist` or `remove_safelist` accordingly.
 
 ## Scan ID
 
-Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`) return a `scan_id` that references message IDs stored server-side. This keeps thousands of message IDs out of the conversation context. `gmail_outreach_scan` is a pure data aggregation tool - it finds senders without List-Unsubscribe headers (potential cold outreach) and does not use LLM classification.
+Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`) return a `scan_id` that references message IDs stored server-side. This keeps thousands of message IDs out of the conversation context. `gmail_outreach_scan` finds senders without List-Unsubscribe headers (potential cold outreach) and enriches each sender with `has_prior_reply` (whether the user has ever sent an email to that address). Use this signal to filter out legitimate correspondents before classifying cold outreach.
 
 - Pass `scan_id` + `sender_ids` to `gmail_archive` instead of `message_ids`
-- Scan results expire after **30 minutes** - if archiving fails with an expiration error, re-run the scan
+- Scan results expire after **30 minutes**. When a scan expires (`resolved === null`), archiving automatically falls back to query-based archiving per sender. If sender IDs don't match the scan results (`resolved` is empty), the tool returns an error — re-run the scan to get fresh results.
 - Raw `message_ids` still work as a fallback for non-scan workflows
 
 ## Batch Operations

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

@@ -494,15 +494,15 @@
           },
           "max_messages": {
             "type": "number",
-            "description": "Maximum messages to scan (default 5000, cap 10000)"
+            "description": "Maximum messages to scan (default 2000, cap 5000)"
           },
           "max_senders": {
             "type": "number",
-            "description": "Maximum senders to return (default 50)"
+            "description": "Maximum senders to return (default 50, max 75)"
           },
           "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)"
+            "description": "Resume token from a previous scan (rarely needed - scans now cover up to 5,000 messages in a single call)"
           },
           "activity": {
             "type": "string",
@@ -553,6 +553,36 @@
       },
       "executor": "tools/gmail-outreach-scan.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "gmail_preferences",
+      "description": "Manage Gmail cleanup preferences (blocklist and safelist). The blocklist contains senders to auto-archive in future cleanups. The safelist contains senders the user wants to keep (excluded from cleanup tables).",
+      "category": "gmail",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["list", "add_blocklist", "add_safelist", "remove_blocklist", "remove_safelist"],
+            "description": "Preference action: list all preferences, or add/remove emails from blocklist or safelist"
+          },
+          "emails": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Email addresses to add or remove (required for add/remove actions)"
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action"]
+      },
+      "executor": "tools/gmail-preferences-tool.ts",
+      "execution_target": "host"
     }
   ]
 }

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

@@ -8,12 +8,49 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
+import { addToBlocklist } from "./gmail-preferences.js";
 import { getSenderMessageIds } from "./scan-result-store.js";
 import { err, ok } from "./shared.js";
 
 const BATCH_MODIFY_LIMIT = 1000;
 const MAX_MESSAGES = 5000;
 
+function decodeSenderEmail(senderId: string): string | null {
+  try {
+    return Buffer.from(senderId, "base64url").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist archived sender emails to the blocklist for future sessions.
+ * Only runs when the archive was initiated via a validated scan_id path
+ * (not bare message_ids) to prevent unverified emails from being recorded.
+ */
+function recordBlocklist(
+  scanId: string | undefined,
+  senderIds: string[] | undefined,
+): void {
+  if (!scanId || !senderIds?.length) return;
+  const archivedEmails: string[] = [];
+  for (const sid of senderIds) {
+    try {
+      const email = Buffer.from(sid, "base64url").toString("utf-8");
+      if (email.includes("@")) archivedEmails.push(email);
+    } catch {
+      // Skip undecodable sender IDs
+    }
+  }
+  if (archivedEmails.length > 0) {
+    try {
+      addToBlocklist(archivedEmails);
+    } catch {
+      // Non-fatal — preferences are best-effort
+    }
+  }
+}
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -28,9 +65,9 @@ export async function run(
   // 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) {
+    if (!context.triggeredBySurfaceAction && !context.batchAuthorizedByTask) {
       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.",
+        "This tool requires either a surface action or a scheduled task run with this tool in required_tools. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
       );
     }
 
@@ -83,24 +120,92 @@ export async function run(
     }
   } else if (scanId && senderIds?.length) {
     // Scan path requires surface action confirmation
-    if (!context.triggeredBySurfaceAction) {
+    if (!context.triggeredBySurfaceAction && !context.batchAuthorizedByTask) {
       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.",
+        "This tool requires either a surface action or a scheduled task run with this tool in required_tools. 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) {
+    if (resolved !== null && resolved.length > 0) {
+      messageIds = resolved;
+    } else if (resolved === null) {
+      // Scan expired or sender IDs unresolved — fall back to query-based archiving
+      const emails: string[] = [];
+      const undecodable: string[] = [];
+      for (const sid of senderIds) {
+        const email = decodeSenderEmail(sid);
+        if (email && email.includes("@")) {
+          emails.push(email);
+        } else {
+          undecodable.push(sid);
+        }
+      }
+
+      if (emails.length === 0) {
+        return err(
+          "Scan results have expired and sender IDs could not be decoded. Please re-run the scan.",
+        );
+      }
+
+      try {
+        const connection = await resolveOAuthConnection("google", {
+          account,
+        });
+        const allMessageIds: string[] = [];
+
+        for (const email of emails) {
+          const fallbackQuery = `from:"${email.replace(/"/g, "")}" in:inbox`;
+          let pageToken: string | undefined;
+          while (allMessageIds.length < MAX_MESSAGES) {
+            const listResp = await listMessages(
+              connection,
+              fallbackQuery,
+              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) break;
+        }
+
+        if (allMessageIds.length === 0) {
+          return ok("No inbox messages found for the selected senders.");
+        }
+
+        for (let i = 0; i < allMessageIds.length; i += BATCH_MODIFY_LIMIT) {
+          const chunk = allMessageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+          await batchModifyMessages(connection, chunk, {
+            removeLabelIds: ["INBOX"],
+          });
+        }
+
+        const parts = [
+          `Archived ${allMessageIds.length} message(s) via query fallback (scan results had expired).`,
+        ];
+        if (undecodable.length > 0) {
+          parts.push(
+            `${undecodable.length} sender ID(s) could not be decoded and were skipped.`,
+          );
+        }
+        return ok(parts.join(" "));
+      } catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+      }
+    } else {
       return err(
-        "Scan results have expired (30-minute window). Please re-run the scan to get fresh results.",
+        "The provided sender IDs do not match the scan results. Please re-run the scan.",
       );
     }
-    messageIds = resolved;
   } else if (messageIds?.length) {
     // Batch message_ids path requires surface action confirmation
-    if (!context.triggeredBySurfaceAction) {
+    if (!context.triggeredBySurfaceAction && !context.batchAuthorizedByTask) {
       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.",
+        "This tool requires either a surface action or a scheduled task run with this tool in required_tools. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
       );
     }
   } else if (messageId) {
@@ -133,6 +238,7 @@ export async function run(
       await modifyMessage(connection, messageIds[0], {
         removeLabelIds: ["INBOX"],
       });
+      recordBlocklist(scanId, senderIds);
       return ok("Message archived.");
     }
 
@@ -142,6 +248,7 @@ export async function run(
         removeLabelIds: ["INBOX"],
       });
     }
+    recordBlocklist(scanId, senderIds);
     return ok(`Archived ${messageIds.length} message(s).`);
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));

package/src/config/bundled-skills/gmail/tools/gmail-outreach-scan.ts

@@ -11,6 +11,11 @@ import type {
 import { storeScanResult } from "./scan-result-store.js";
 import { err, ok } from "./shared.js";
 
+function isRateLimitError(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  return /\b429\b/.test(e.message);
+}
+
 const MAX_MESSAGES_CAP = 5000;
 const MAX_IDS_PER_SENDER = 5000;
 const MAX_SAMPLE_SUBJECTS = 3;
@@ -69,6 +74,8 @@ export async function run(
     const startTime = Date.now();
     const TIME_BUDGET_MS = 90_000;
 
+    let rateLimited = false;
+
     while (allMessageIds.length < maxMessages) {
       if (Date.now() - startTime > TIME_BUDGET_MS) {
         timeBudgetExceeded = true;
@@ -76,12 +83,17 @@ export async function run(
         break;
       }
       const pageSize = Math.min(100, maxMessages - allMessageIds.length);
-      const listResp = await listMessages(
-        connection,
-        query,
-        pageSize,
-        pageToken,
-      );
+      let listResp;
+      try {
+        listResp = await listMessages(connection, query, pageSize, pageToken);
+      } catch (e) {
+        if (isRateLimitError(e)) {
+          rateLimited = true;
+          truncated = true;
+          break;
+        }
+        throw e;
+      }
       const ids = (listResp.messages ?? []).map((m) => m.id);
       if (ids.length === 0) break;
       allMessageIds.push(...ids);
@@ -103,6 +115,17 @@ export async function run(
     }
 
     if (allMessageIds.length === 0) {
+      if (rateLimited) {
+        return ok(
+          JSON.stringify({
+            senders: [],
+            total_scanned: 0,
+            rate_limited: true,
+            truncated: true,
+            note: "Rate limited before any messages could be fetched. Try again later or reduce max_messages.",
+          }),
+        );
+      }
       return ok(
         JSON.stringify({
           senders: [],
@@ -112,7 +135,35 @@ export async function run(
       );
     }
 
-    const messages = (await Promise.all(fetchPromises)).flat();
+    // Settle all fetch promises — collect successes and tolerate 429 failures.
+    const elapsedMs = Date.now() - startTime;
+    const settleDeadlineMs = Math.max(TIME_BUDGET_MS - elapsedMs, 5_000);
+    const deadlineRejection = new Promise<never>((_, reject) =>
+      setTimeout(
+        () => reject(new Error("fetch deadline exceeded")),
+        settleDeadlineMs,
+      ),
+    );
+    const settled = await Promise.allSettled(
+      fetchPromises.map((p) => Promise.race([p, deadlineRejection])),
+    );
+    const messages: GmailMessage[] = [];
+    for (const result of settled) {
+      if (result.status === "fulfilled") {
+        messages.push(...result.value);
+      } else if (isRateLimitError(result.reason)) {
+        rateLimited = true;
+        truncated = true;
+      } else if (
+        result.reason instanceof Error &&
+        result.reason.message === "fetch deadline exceeded"
+      ) {
+        timeBudgetExceeded = true;
+        truncated = true;
+      } else {
+        throw result.reason;
+      }
+    }
 
     // Aggregate all fetched messages by sender
     const senderMap = new Map<string, OutreachSenderAggregation>();
@@ -177,16 +228,91 @@ export async function run(
       }
     }
 
-    // Sort by message count desc, take top N
+    // Sort by message count desc — over-fetch before enrichment, cap after
     const sorted = [...senderMap.values()]
       .sort((a, b) => b.messageCount - a.messageCount)
-      .slice(0, maxSenders);
+      .slice(0, maxSenders * 3);
+
+    // Enrich with prior-reply signal: check if user has ever sent to each sender.
+    // Uses bounded concurrency (batches of 10) and AbortController to cancel
+    // in-flight requests when the time budget expires.
+    const ENRICHMENT_CONCURRENCY = 10;
+    const priorReplyMap = new Map<string, boolean>();
+    if (!rateLimited) {
+      const enrichmentBudgetMs = Math.max(
+        TIME_BUDGET_MS - (Date.now() - startTime),
+        5_000,
+      );
+      const abortController = new AbortController();
+      const budgetTimer = setTimeout(
+        () => abortController.abort(),
+        enrichmentBudgetMs,
+      );
+
+      try {
+        // Process in waves to limit concurrency and stop on budget expiry
+        for (
+          let i = 0;
+          i < sorted.length && !abortController.signal.aborted;
+          i += ENRICHMENT_CONCURRENCY
+        ) {
+          const batch = sorted.slice(i, i + ENRICHMENT_CONCURRENCY);
+          const batchChecks = batch.map(async (s) => {
+            if (abortController.signal.aborted) return;
+            try {
+              const resp = await listMessages(
+                connection,
+                `from:me to:${s.email}`,
+                1,
+              );
+              priorReplyMap.set(s.email, (resp.messages?.length ?? 0) > 0);
+            } catch {
+              // Non-fatal — default to safe direction (assume prior reply exists)
+              priorReplyMap.set(s.email, true);
+            }
+          });
+          await Promise.race([
+            Promise.all(batchChecks),
+            new Promise<void>((resolve) =>
+              abortController.signal.addEventListener(
+                "abort",
+                () => resolve(),
+                {
+                  once: true,
+                },
+              ),
+            ),
+          ]);
+        }
+      } finally {
+        clearTimeout(budgetTimer);
+      }
+
+      // Default any un-enriched senders to safe direction
+      for (const s of sorted) {
+        if (!priorReplyMap.has(s.email)) {
+          priorReplyMap.set(s.email, true);
+        }
+      }
+    } else {
+      // Rate limited — default all to safe direction
+      for (const s of sorted) {
+        priorReplyMap.set(s.email, true);
+      }
+    }
 
-    const senders = sorted.map((s) => ({
+    // Filter out senders with prior replies, then cap to maxSenders.
+    // This is the purpose of over-fetching (maxSenders * 3): enrich more
+    // candidates, discard those with existing replies, then take the top N.
+    const capped = sorted
+      .filter((s) => !priorReplyMap.get(s.email))
+      .slice(0, maxSenders);
+    const senders = capped.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_prior_reply: priorReplyMap.get(s.email) ?? true,
       newest_message_id: s.newestMessageId,
       oldest_date: s.oldestDate,
       newest_date: s.newestDate,
@@ -196,7 +322,7 @@ export async function run(
 
     // Store message IDs server-side to keep them out of LLM context
     const scanId = storeScanResult(
-      sorted.map((s) => ({
+      capped.map((s) => ({
         id: Buffer.from(s.email).toString("base64url"),
         messageIds: s.messageIds,
         newestMessageId: s.newestMessageId,
@@ -211,6 +337,7 @@ export async function run(
         total_scanned: allMessageIds.length,
         ...(truncated ? { truncated: true } : {}),
         ...(timeBudgetExceeded ? { time_budget_exceeded: true } : {}),
+        ...(rateLimited ? { rate_limited: true } : {}),
         note: "Scanned inbox for senders without List-Unsubscribe headers (potential cold outreach). Use gmail_archive and gmail_filters for cleanup.",
       }),
     );

package/src/config/bundled-skills/gmail/tools/gmail-preferences-tool.ts

@@ -0,0 +1,59 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import {
+  addToBlocklist,
+  addToSafelist,
+  loadPreferences,
+  removeFromBlocklist,
+  removeFromSafelist,
+} from "./gmail-preferences.js";
+import { err, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const action = input.action as string;
+  const emails = input.emails as string[] | undefined;
+
+  switch (action) {
+    case "list": {
+      const prefs = loadPreferences();
+      return ok(
+        JSON.stringify({
+          blocklist_count: prefs.blocklist.length,
+          safelist_count: prefs.safelist.length,
+          blocklist: prefs.blocklist,
+          safelist: prefs.safelist,
+        }),
+      );
+    }
+    case "add_blocklist": {
+      if (!emails?.length) return err("emails is required for add_blocklist");
+      addToBlocklist(emails);
+      return ok(`Added ${emails.length} sender(s) to blocklist.`);
+    }
+    case "add_safelist": {
+      if (!emails?.length) return err("emails is required for add_safelist");
+      addToSafelist(emails);
+      return ok(`Added ${emails.length} sender(s) to safelist.`);
+    }
+    case "remove_blocklist": {
+      if (!emails?.length)
+        return err("emails is required for remove_blocklist");
+      removeFromBlocklist(emails);
+      return ok(`Removed ${emails.length} sender(s) from blocklist.`);
+    }
+    case "remove_safelist": {
+      if (!emails?.length) return err("emails is required for remove_safelist");
+      removeFromSafelist(emails);
+      return ok(`Removed ${emails.length} sender(s) from safelist.`);
+    }
+    default:
+      return err(
+        `Unknown action "${action}". Use list, add_blocklist, add_safelist, remove_blocklist, or remove_safelist.`,
+      );
+  }
+}