@vellumai/assistant 0.6.2 → 0.6.4

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

@@ -13,10 +13,12 @@ metadata:
 
 Use this skill to browse the web. After loading this skill, the following browser tools become available:
 
+- `browser_attach` - Attach the Chrome debugger to the active tab
 - `browser_navigate` - Navigate to a URL
 - `browser_snapshot` - List interactive elements on the current page
 - `browser_screenshot` - Take a visual screenshot
 - `browser_close` - Close the browser page
+- `browser_detach` - Detach the Chrome debugger from the active tab
 - `browser_click` - Click an element
 - `browser_type` - Type text into an input
 - `browser_press_key` - Press a keyboard key
@@ -27,18 +29,41 @@ Use this skill to browse the web. After loading this skill, the following browse
 - `browser_extract` - Extract page text content
 - `browser_wait_for_download` - Wait for a file download to complete
 - `browser_fill_credential` - Fill a stored credential into a form field
+- `browser_status` - Diagnose browser backend readiness and setup steps
 
 ## Capabilities
 
 This browser runs **full Chromium with JavaScript enabled**. It can handle SPAs, React/Vue/Angular apps, dynamic content, date pickers, booking systems, reservation flows, and any JavaScript-heavy interactive site. Never tell the user you "can't handle interactive JavaScript" - you can.
 
+## Browser Mode
+
+Every browser tool accepts an optional `browser_mode` parameter that controls which backend executes the command:
+
+| Value | Backend | Description |
+|---|---|---|
+| `auto` | Automatic | Default. The assistant picks the best available backend based on context (extension > cdp-inspect > local). |
+| `extension` | Chrome extension | Routes through the user's Chrome browser via the extension debugger. |
+| `cdp-inspect` | CDP inspect | Connects to an already-running Chrome instance via the DevTools protocol. Alias: `cdp-debugger`. |
+| `local` | Playwright | Drives a dedicated Playwright-managed Chromium instance. Alias: `playwright`. |
+
+**When to use `auto`**: Prefer `auto` (or omit `browser_mode` entirely) unless you have a specific reason to pin. The automatic backend selection handles extension availability, fallback, and session reuse.
+
+**When to pin a mode**: Pin explicitly when:
+- The user requests interaction with their own browser (use `extension` or `cdp-inspect`).
+- A tool only works on a specific backend (e.g. `browser_wait_for_download` requires `local`).
+- You want to avoid fallback behavior for diagnostic clarity.
+
+**Unsupported mode errors**: Some tools restrict which modes they support. For example, `browser_wait_for_download` only supports `auto` and `local` because file downloads require the Playwright backend. Passing an unsupported mode returns a clear error with the accepted alternatives.
+
 ## Typical Workflow
 
-1. `browser_navigate` to load a page
-2. `browser_snapshot` to discover interactive elements
-3. Use `browser_click`, `browser_type`, `browser_press_key`, `browser_scroll`, `browser_select_option`, or `browser_hover` to interact
-4. `browser_extract` or `browser_screenshot` to capture results
-5. `browser_close` when done
+1. (Optional) `browser_status` to diagnose backend availability and remediation when setup is unclear
+2. `browser_attach` to establish the debugger session (extension path; optional on other backends)
+3. `browser_navigate` to load a page
+4. `browser_snapshot` to discover interactive elements
+5. Use `browser_click`, `browser_type`, `browser_press_key`, `browser_scroll`, `browser_select_option`, or `browser_hover` to interact
+6. `browser_extract` or `browser_screenshot` to capture results
+7. `browser_detach` to end the debugger session, or `browser_close` to close the page entirely
 
 ## Interaction Strategies
 

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

@@ -17,6 +17,10 @@
             "type": "boolean",
             "description": "If true, allows navigation to localhost/private-network hosts. Disabled by default for SSRF safety."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -35,6 +39,10 @@
       "input_schema": {
         "type": "object",
         "properties": {
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -56,6 +64,10 @@
             "type": "boolean",
             "description": "Capture the full scrollable page instead of just the viewport."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -77,6 +89,10 @@
             "type": "boolean",
             "description": "If true, close all browser pages and the browser context. Default: false (close only the current conversation page)."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -86,6 +102,48 @@
       "executor": "tools/browser-close.ts",
       "execution_target": "host"
     },
+    {
+      "name": "browser_attach",
+      "description": "Explicitly attach the Chrome debugger to the active browser tab. Use at the start of a browser session to establish the debugging connection before navigating or interacting. On the extension path this attaches the debugger; on other backends this is a no-op that returns success.",
+      "category": "browser",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/browser-attach.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "browser_detach",
+      "description": "Explicitly detach the Chrome debugger from the active browser tab. Use when done with browser interaction to cleanly end the debugging session. On the extension path this detaches the debugger and clears the Chrome debugging banner; on other backends this clears stale snapshot state.",
+      "category": "browser",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/browser-detach.ts",
+      "execution_target": "host"
+    },
     {
       "name": "browser_click",
       "description": "Click an element on the page. Always use element_id from browser_snapshot \u2014 do not fabricate CSS selectors. For native <select> elements, use browser_select_option instead. For ARIA/custom dropdowns (mat-select, role=listbox, or any dropdown whose options appear as role=\"option\" in browser_snapshot), click to open, take a new browser_snapshot, then click the desired option by element_id. For autocomplete inputs where options don't appear in the snapshot, use browser_press_key with ArrowDown/ArrowUp + Enter.",
@@ -102,6 +160,10 @@
             "type": "string",
             "description": "A CSS selector to target. Used as fallback when element_id is not available."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -139,6 +201,10 @@
             "type": "boolean",
             "description": "If true, press Enter after typing the text."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -169,6 +235,10 @@
             "type": "string",
             "description": "Optional CSS selector to target."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -204,6 +274,10 @@
             "type": "string",
             "description": "Optional CSS selector of element to scroll within."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -242,6 +316,10 @@
             "type": "number",
             "description": "The zero-based index of the <option> to select."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -267,6 +345,10 @@
             "type": "string",
             "description": "A CSS selector to target. Used as fallback when element_id is not available."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -300,6 +382,10 @@
             "type": "number",
             "description": "Maximum wait time in milliseconds (default and max: 30000)."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -321,6 +407,10 @@
             "type": "boolean",
             "description": "If true, include a list of links found on the page (up to 200)."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -342,6 +432,10 @@
             "type": "number",
             "description": "Maximum wait time in milliseconds (default: 30000, max: 120000)."
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Only auto (default) and local (alias: playwright) are supported for this tool — file downloads require the local Playwright backend. Other modes (extension, cdp-inspect) are not supported and will be rejected."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -379,6 +473,10 @@
             "type": "boolean",
             "description": "Press Enter after filling"
           },
+          "browser_mode": {
+            "type": "string",
+            "description": "Override backend selection. Values: auto (default), extension, cdp-inspect (alias: cdp-debugger), local (alias: playwright). Omit or use auto to let the assistant choose."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -388,6 +486,31 @@
       },
       "executor": "tools/browser-fill-credential.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "browser_status",
+      "description": "Check browser backend readiness and remediation guidance. Reports per-mode availability, verification method, setup steps, and trade-offs for extension, cdp-inspect, and local Playwright modes.",
+      "category": "browser",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "browser_mode": {
+            "type": "string",
+            "description": "Optional scope override for this status check. Use auto (default) to check all modes, or set extension/cdp-inspect/local to check only one mode. Aliases: cdp-debugger -> cdp-inspect, playwright -> local."
+          },
+          "check_local_launch": {
+            "type": "boolean",
+            "description": "If true, run an active local Playwright launch probe. Default false (preflight-only) to avoid creating a new local browser page during diagnostics."
+          },
+          "activity": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        }
+      },
+      "executor": "tools/browser-status.ts",
+      "execution_target": "host"
     }
   ]
 }

package/src/config/bundled-skills/browser/tools/browser-attach.ts

@@ -0,0 +1,12 @@
+import { executeBrowserAttach } from "../../../../tools/browser/browser-execution.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeBrowserAttach(input, context);
+}

package/src/config/bundled-skills/browser/tools/browser-detach.ts

@@ -0,0 +1,12 @@
+import { executeBrowserDetach } from "../../../../tools/browser/browser-execution.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeBrowserDetach(input, context);
+}

package/src/config/bundled-skills/browser/tools/browser-status.ts

@@ -0,0 +1,12 @@
+import { executeBrowserStatus } from "../../../../tools/browser/browser-execution.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeBrowserStatus(input, context);
+}

package/src/config/bundled-skills/browser/tools/browser-wait-for-download.ts

@@ -1,4 +1,5 @@
 import { browserManager } from "../../../../tools/browser/browser-manager.js";
+import { normalizeBrowserMode } from "../../../../tools/browser/browser-mode.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -8,6 +9,22 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  // Validate browser_mode: only auto/local are supported for downloads.
+  const modeResult = normalizeBrowserMode(input.browser_mode);
+  if ("error" in modeResult) {
+    return { content: `Error: ${modeResult.error}`, isError: true };
+  }
+  const { mode } = modeResult;
+  if (mode !== "auto" && mode !== "local") {
+    return {
+      content:
+        `Error: browser_wait_for_download does not support browser_mode "${mode}". ` +
+        `File downloads require the local Playwright backend. ` +
+        `Use browser_mode "auto" or "local" instead.`,
+      isError: true,
+    };
+  }
+
   const timeout =
     typeof input.timeout === "number"
       ? Math.min(Math.max(input.timeout, 1000), 120_000)

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

@@ -6,6 +6,9 @@ metadata:
   emoji: "👥"
   vellum:
     display-name: "Contacts"
+    activation-hints:
+      - "Look up contact info before asking the user for email addresses or phone numbers"
+      - "User wants to manage who can message the assistant, or create/revoke invite links"
 ---
 
 Manage the user's contacts, relationship graph, access control (trusted contacts), and invite links. This skill covers contact CRUD with multi-channel tracking, controlling who can message the assistant through external channels (Telegram, phone), and creating/managing invite links that grant access.
@@ -305,7 +308,7 @@ The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInst
 
 - `inviteCode` is the 6-digit code the invitee must send to redeem the invite. It is only returned at creation time.
 - `guardianInstruction` is a generated instruction telling the guardian how to share the invite.
-- `channelHandle` is the assistant's email address (e.g. `hello@domain.agentmail.to`).
+- `channelHandle` is the assistant's email address (e.g. `hello@vellum.me`).
 
 **Presenting to the guardian**: Give the guardian the invite code and the assistant's email address:
 
@@ -317,7 +320,7 @@ The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInst
 >
 > This code can be used <maxUses> time(s)<and expires in X hours/days if applicable>.
 
-If the assistant's email address is not available (AgentMail not configured), tell the guardian they need to set up email integration first.
+If the assistant's email address is not available, tell the guardian they need to register one with `assistant email register <username>`.
 
 ### Create a WhatsApp invite
 

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

@@ -6,6 +6,10 @@ metadata:
   emoji: "📄"
   vellum:
     display-name: "Document"
+    activation-hints:
+      - "User asks to write, draft, or collaborate on long-form content — use the document editor for a better editing experience"
+      - "When content will be iterated on, reviewed, or exported, prefer the document editor over inline markdown"
+      - "When a file attachment contains a draft or document the user wants to iterate on, open it in the editor"
 ---
 
 Create and edit long-form documents using the built-in rich text editor. Documents open in workspace mode with chat docked to the side.

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
@@ -161,7 +207,7 @@ Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`) return a `scan_id` tha
 
 Before composing any email that references a date or time:
 
-1. Check the `timestamp:` field in the `<turn_context>` block for today's date and timezone
+1. Check the `current_time:` field in the `<turn_context>` block for today's date and timezone
 2. Verify that "tomorrow" means the day after today's date, "next week" means the upcoming Monday–Friday, etc.
 3. If the email references a date from another message, cross-check it against the turn context to ensure it's in the future
 

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"
     }
   ]
 }