@vellumai/assistant 0.4.11 → 0.4.13

package/src/config/bundled-skills/google-oauth-setup/SKILL.md

@@ -20,7 +20,7 @@ Determine whether the user has browser automation available (macOS desktop app)
 
 # Path A: Manual Setup for Channels (Telegram, SMS, etc.)
 
-When the user is on Telegram or any non-macOS client, walk them through a text-based setup. No browser automation is used — the user follows links and performs each action manually.
+When the user is on Telegram or any non-macOS client, walk them through a text-based setup. No browser automation is used; the user follows links and performs each action manually.
 
 ### Channel Step 1: Confirm and Explain
 
@@ -47,7 +47,7 @@ Tell the user:
 >
 > Set the project name to **"Vellum Assistant"** and click **Create**.
 >
-> Let me know when it's done (or if you already have a project you'd like to use — just tell me the project ID).
+> Let me know when it's done (or if you already have a project you'd like to use, just tell me the project ID).
 
 Wait for confirmation. Note the project ID for subsequent steps.
 
@@ -115,13 +115,13 @@ Tell the user:
 > 4. Under **Authorized redirect URIs**, click **Add URI** and paste the redirect URI shown above
 > 5. Click **Create**
 >
-> A dialog will show your **Client ID** and **Client Secret**. Copy both values — you'll need them in the next step.
+> A dialog will show your **Client ID** and **Client Secret**. Copy both values, you'll need them in the next step.
 
 **Important:** Channel users must use **"Web application"** credentials (not Desktop app) because the OAuth callback goes through the gateway URL.
 
 ### Channel Step 6: Store Credentials
 
-**Step 6a — Client ID (safe to send in chat):**
+**Step 6a: Client ID (safe to send in chat)**
 
 Tell the user:
 
@@ -138,7 +138,7 @@ credential_store store:
   value: "<the Client ID the user sent>"
 ```
 
-**Step 6b — Client Secret (requires split entry to avoid security filters):**
+**Step 6b: Client Secret (requires split entry to avoid security filters)**
 
 The Client Secret starts with `GOCSPX-` which triggers the ingress secret scanner on channel messages. To work around this, ask the user to send only the portion *after* the prefix.
 
@@ -200,7 +200,7 @@ You will automate the entire GCP setup via the browser while the user watches in
 
 Google Cloud Console's UI changes frequently. Do NOT memorize or depend on specific element IDs, CSS selectors, or DOM structures. Instead:
 
-1. **Snapshot first, act second.** Before every interaction, use `browser_snapshot` to discover interactive elements and their IDs. This is your primary navigation tool — it gives you the accessibility tree with clickable/typeable element IDs. Use `browser_screenshot` for visual context when the snapshot alone isn't enough.
+1. **Snapshot first, act second.** Before every interaction, use `browser_snapshot` to discover interactive elements and their IDs. This is your primary navigation tool; it gives you the accessibility tree with clickable/typeable element IDs. Use `browser_screenshot` for visual context when the snapshot alone isn't enough.
 2. **Adapt to what you see.** If an element's label or position differs from what you expect, use the snapshot to find the correct element. GCP may rename buttons, reorganize menus, or change form layouts at any time.
 3. **Verify after every action.** After clicking, typing, or navigating, take a new snapshot to confirm the action succeeded. If it didn't, try an alternative interaction (e.g., if a dropdown didn't open on click, try pressing Space or Enter on the element).
 4. **Never assume DOM structure.** Dropdowns may be `<select>`, `<mat-select>`, `<div role="listbox">`, or something else entirely. Use the snapshot to identify element types and interact accordingly.
@@ -214,31 +214,31 @@ Each step has a **retry budget of 3 attempts**. An attempt is one try at the ste
 2. **Fall back to manual.** Tell the user what you were trying to do and ask them to complete that step manually in the Chrome window (which they can see on the side). Give them the direct URL and clear text instructions.
 3. **Resume automation** at the next step once the user confirms the manual step is done.
 
-If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links — using "Desktop app" as the OAuth application type.
+If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links, using "Desktop app" as the OAuth application type.
 
-## Things That Do Not Work — Do Not Attempt
+## Things That Do Not Work: Do Not Attempt
 
 These actions are technically impossible in the browser automation environment. Attempting them wastes time and leads to loops:
 
 - **Downloading files.** `browser_click` on a Download button does not save files to disk. There is NO JSON file to find at `~/Downloads` or anywhere else. Never click Download buttons.
 - **Clipboard operations.** You cannot copy/paste via browser automation. The user must manually copy values from the Chrome window.
-- **Deleting and recreating OAuth clients** to get a fresh secret — this orphans the stored client_id and causes `invalid_client` errors.
-- **Navigating away from the credential dialog** before both credentials are stored — you will lose the Client Secret display and cannot get it back without creating a new client.
+- **Deleting and recreating OAuth clients** to get a fresh secret. This orphans the stored client_id and causes `invalid_client` errors.
+- **Navigating away from the credential dialog** before both credentials are stored. You will lose the Client Secret display and cannot get it back without creating a new client.
 
 ## Step 1: Single Upfront Confirmation
 
-Use `ui_show` with `surface_type: "confirmation"` and this message:
+Use `ui_show` with `surface_type: "confirmation"`. Set `message` to just the title, and `detail` to the body:
 
-> **Set up Google Cloud for Gmail & Calendar**
->
-> Here's what will happen:
-> 1. **A browser opens on the side** — you'll be able to watch everything I do
-> 2. **You sign in** to your Google account in the browser
-> 3. **I automate everything** — project creation, APIs, OAuth config, credentials
-> 4. **One copy-paste** — I'll ask you to copy the Client Secret from the browser into a secure prompt
-> 5. **You authorize Vellum** with one click
->
-> The whole thing takes 2-3 minutes. Ready?
+- **message:** `Set up Google Cloud for Gmail & Calendar`
+- **detail:**
+  > Here's what will happen:
+  > 1. **A browser opens on the side** so you can watch everything I do
+  > 2. **You sign in** to your Google account in the browser
+  > 3. **I automate everything** including project creation, APIs, OAuth config, and credentials
+  > 4. **One copy-paste** where I'll ask you to copy the Client Secret from the browser into a secure prompt
+  > 5. **You authorize Vellum** with one click
+  >
+  > The whole thing takes 2-3 minutes. Ready?
 
 If the user declines, acknowledge and stop. No further confirmations are needed after this point.
 
@@ -250,9 +250,9 @@ Navigate to `https://console.cloud.google.com/`.
 
 Take a screenshot to check the page state:
 
-- **Sign-in page:** Tell the user: "Please sign in to your Google account in the Chrome window on the right side of your screen." Then auto-detect sign-in completion by polling with `browser_screenshot` every 5-10 seconds — check if the URL has moved away from `accounts.google.com` to `console.cloud.google.com`. Do NOT ask the user to "let me know when you're done" — detect it automatically. Once sign-in is detected, tell the user: "Signed in! Starting the automated setup now..."
-- **Already signed in:** Tell the user: "Already signed in — starting setup now..." and continue immediately.
-- **CAPTCHA:** The browser automation's built-in handoff will handle this. If it persists, tell the user: "There's a CAPTCHA in the browser — please complete it and I'll continue automatically."
+- **Sign-in page:** Tell the user: "Please sign in to your Google account in the Chrome window on the right side of your screen." Then auto-detect sign-in completion by polling with `browser_screenshot` every 5-10 seconds to check if the URL has moved away from `accounts.google.com` to `console.cloud.google.com`. Do NOT ask the user to "let me know when you're done"; detect it automatically. Once sign-in is detected, tell the user: "Signed in! Starting the automated setup now..."
+- **Already signed in:** Tell the user: "Already signed in, starting setup now..." and continue immediately.
+- **CAPTCHA:** The browser automation's built-in handoff will handle this. If it persists, tell the user: "There's a CAPTCHA in the browser, please complete it and I'll continue automatically."
 
 **What you should see when done:** URL contains `console.cloud.google.com` and no sign-in overlay is visible.
 
@@ -266,10 +266,10 @@ Navigate to `https://console.cloud.google.com/projectcreate`.
 
 Take a `browser_snapshot`. Find the project name input field (look for an element with label containing "Project name" or a text input near the top of the form). Type "Vellum Assistant" into it.
 
-Look for a "Create" button in the snapshot and click it. Wait 10-15 seconds for project creation — take a screenshot to check for:
-- **Success message** or redirect to the new project dashboard — note the project ID from the URL or page content.
-- **"Project name already in use" error** — that's fine. Navigate to `https://console.cloud.google.com/cloud-resource-manager` to find and select the existing "Vellum Assistant" project. Use `browser_extract` to read the project ID from the page.
-- **Organization restriction or quota error** — tell the user what happened and ask them to resolve it.
+Look for a "Create" button in the snapshot and click it. Wait 10-15 seconds for project creation, then take a screenshot to check for:
+- **Success message** or redirect to the new project dashboard. Note the project ID from the URL or page content.
+- **"Project name already in use" error**: that's fine. Navigate to `https://console.cloud.google.com/cloud-resource-manager` to find and select the existing "Vellum Assistant" project. Use `browser_extract` to read the project ID from the page.
+- **Organization restriction or quota error**: tell the user what happened and ask them to resolve it.
 
 **What you should see when done:** The project selector in the top bar shows the project name, and you have the project ID (something like `vellum-assistant-12345`).
 
@@ -286,8 +286,8 @@ Navigate to each API's library page and enable it if not already enabled:
 2. `https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=PROJECT_ID`
 
 For each page: take a `browser_snapshot`. Look for:
-- **"Enable" button** — click it, wait a few seconds, take another snapshot to confirm.
-- **"Manage" button or "API enabled" text** — the API is already enabled. Skip it.
+- **"Enable" button**: click it, wait a few seconds, take another snapshot to confirm.
+- **"Manage" button or "API enabled" text**: the API is already enabled. Skip it.
 
 **What you should see when done:** Both API pages show "Manage" or "API enabled" status.
 
@@ -297,7 +297,7 @@ Tell the user: "APIs enabled!"
 
 **Goal:** An OAuth consent screen is configured with External user type, the required scopes, and the user added as a test user.
 
-Tell the user: "Setting up OAuth consent screen — this is the longest step but it's fully automated..."
+Tell the user: "Setting up OAuth consent screen. This is the longest step but it's fully automated..."
 
 Navigate to `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`.
 
@@ -354,12 +354,12 @@ Tell the user: "Creating OAuth credentials..."
 
 Navigate to `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`.
 
-Take a `browser_snapshot`. Find and click a button labeled **"Create Credentials"** or **"+ Create Credentials"**. A dropdown menu should appear — take another snapshot and click **"OAuth client ID"**.
+Take a `browser_snapshot`. Find and click a button labeled **"Create Credentials"** or **"+ Create Credentials"**. A dropdown menu should appear. Take another snapshot and click **"OAuth client ID"**.
 
 On the creation form (take a snapshot to see the fields):
-- **Application type**: Find the dropdown and select **"Desktop app"**. This may be a `<select>` element or a custom dropdown — use the snapshot to identify it. You might need to click the dropdown first, then take another snapshot to see the options, then click "Desktop app".
+- **Application type**: Find the dropdown and select **"Desktop app"**. This may be a `<select>` element or a custom dropdown. Use the snapshot to identify it. You might need to click the dropdown first, then take another snapshot to see the options, then click "Desktop app".
 - **Name**: Type "Vellum Assistant" in the name field.
-- Do NOT add any redirect URIs — the desktop app flow doesn't need them.
+- Do NOT add any redirect URIs. The desktop app flow doesn't need them.
 
 Click **"Create"** to submit the form.
 
@@ -387,9 +387,9 @@ credential_store prompt:
   placeholder: "xxxxx.apps.googleusercontent.com"
 ```
 
-**Then** — whether the Client ID was auto-read or prompted — tell the user:
+**Then**, whether the Client ID was auto-read or prompted, tell the user:
 
-> "Got the Client ID! Now I need the Client Secret. You can see it in the dialog in the Chrome window — it starts with `GOCSPX-`. Please copy it and paste it into the secure prompt below."
+> "Got the Client ID! Now I need the Client Secret. You can see it in the dialog in the Chrome window. It starts with `GOCSPX-`. Please copy it and paste it into the secure prompt below."
 
 And present the secure prompt:
 
@@ -404,7 +404,7 @@ credential_store prompt:
 
 Wait for the user to complete the prompt. **Do not take any other browser actions until the user has pasted the secret.** The dialog must stay open so they can see and copy the value.
 
-If the user has trouble locating the secret, take a `browser_screenshot` and describe where the secret field is on the screen — but do NOT attempt to read the secret value yourself. It must come from the user for accuracy.
+If the user has trouble locating the secret, take a `browser_screenshot` and describe where the secret field is on the screen, but do NOT attempt to read the secret value yourself. It must come from the user for accuracy.
 
 **What you should see when done:** `credential_store list` shows both `client_id` and `client_secret` for `integration:gmail`.
 
@@ -414,7 +414,7 @@ Tell the user: "Credentials stored securely!"
 
 **Goal:** The user authorizes Vellum to access their Gmail and Calendar via OAuth.
 
-Tell the user: "Opening Google authorization — just click 'Allow' on the consent page."
+Tell the user: "Starting the authorization flow — a Google sign-in page will open in a few seconds. Just click 'Allow' when it appears."
 
 Use `credential_store` with:
 
@@ -425,7 +425,7 @@ service: "integration:gmail"
 
 This auto-reads client_id and client_secret from the secure store and auto-fills auth_url, token_url, scopes, and extra_params from well-known config.
 
-**If the user sees a "This app isn't verified" warning:** Tell them: "You'll see an 'app isn't verified' warning — this is normal for personal apps in testing mode. Click **Advanced**, then **Go to Vellum Assistant (unsafe)** to proceed."
+**If the user sees a "This app isn't verified" warning:** Tell them: "You'll see an 'app isn't verified' warning. This is normal for personal apps in testing mode. Click **Advanced**, then **Go to Vellum Assistant (unsafe)** to proceed."
 
 **Verify:** The `oauth2_connect` call returns a success message with the connected account email.
 
@@ -437,7 +437,7 @@ Tell the user: "**Gmail and Calendar are connected!** You can now read, search,
 
 - **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
 - **Permission errors in GCP:** The user may need billing enabled or organization-level permissions. Explain clearly and ask them to resolve it.
-- **Consent screen already configured:** Don't overwrite — skip to credential creation.
-- **Element not found:** Take a fresh `browser_snapshot` to re-assess. The GCP UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance — they can see the Chrome window too.
+- **Consent screen already configured:** Don't overwrite. Skip to credential creation.
+- **Element not found:** Take a fresh `browser_snapshot` to re-assess. The GCP UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance. They can see the Chrome window too.
 - **OAuth flow timeout or failure:** Offer to retry. The credentials are already stored, so reconnecting only requires re-running the authorization flow.
 - **Any unexpected state:** Take a `browser_screenshot`, describe what you see, and ask the user for guidance.

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

@@ -2,7 +2,7 @@
 name: "Messaging"
 description: "Read, search, send, and manage messages across Slack, Gmail, Telegram, and other platforms"
 user-invocable: true
-metadata: {"vellum": {"emoji": "💬"}}
+metadata: { "vellum": { "emoji": "💬" } }
 ---
 
 You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
@@ -39,10 +39,10 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 3. **Once the provider is known, act immediately.** Don't present setup options or explain OAuth. If it's Gmail, follow the Gmail section below. For any other provider, let the user know that only Gmail is fully supported right now, and offer to set up Gmail instead.
 
 ### Gmail
+
 1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials — so this single call may be all that's needed.
-2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Install and load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "google-oauth-setup"`.
-   - Then call `skill_load` with `skill: "google-oauth-setup"`.
+2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
+   - Call `skill_load` with `skill_id: "google-oauth-setup"` to load the dependency skill.
    - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
      - **message:** "Ready to set up Gmail?"
      - **detail:** "I'll open a browser where you sign in to Google, then automate everything else — creating a project, enabling APIs, and connecting your account. Takes 2-3 minutes and you can watch in the browser preview panel."
@@ -52,10 +52,10 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 3. **If the user provides a client_id directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "gmail"`, and `client_id: "<their value>"`. Include `client_secret` too if they provide one. Everything else is auto-filled.
 
 ### Slack
+
 1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "slack"`. The tool auto-fills Slack's OAuth endpoints and looks up any previously stored client credentials.
-2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill:
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "slack-oauth-setup"`.
-   - Then call `skill_load` with `skill: "slack-oauth-setup"`.
+2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Load the **slack-oauth-setup** skill:
+   - Call `skill_load` with `skill_id: "slack-oauth-setup"` to load the dependency skill.
    - Tell the user Slack isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
      - **message:** "Ready to set up Slack?"
      - **detail:** "I'll walk you through creating a Slack App and connecting your workspace. The process takes a few minutes, and I'll ask for your approval before each step."
@@ -65,20 +65,22 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 3. **If the user provides client_id and client_secret directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "slack"`, `client_id`, and `client_secret`. Everything else is auto-filled. Note: Slack always requires a client_secret.
 
 ### Telegram
-Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** skill (which depends on **public-ingress** for the webhook URL) which automates the full setup:
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "telegram-setup"`.
-   - Then call `skill_load` with `skill: "telegram-setup"`.
-   - Tell the user: *"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."*
+
+Telegram uses a bot token (not OAuth). Load the **telegram-setup** skill (which depends on **public-ingress** for the webhook URL) which automates the full setup:
+
+- Call `skill_load` with `skill_id: "telegram-setup"` to load the dependency skill.
+- Tell the user: _"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."_
 
 The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering bot commands, and storing credentials securely via the secure credential prompt flow. **Never accept a Telegram bot token pasted in plaintext chat — always use the secure prompt.** Webhook registration with Telegram is handled automatically by the gateway on startup and whenever credentials change.
 
 The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot.
 
 ### SMS (Twilio)
+
 SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **sms-setup** skill for complete SMS configuration including compliance and testing:
-   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "sms-setup"`.
-   - Then call `skill_load` with `skill: "sms-setup"`.
-   - Tell the user: *"I've loaded the SMS setup guide. It will walk you through configuring Twilio, handling compliance requirements, and testing SMS delivery."*
+
+- Call `skill_load` with `skill_id: "sms-setup"` to load the dependency skill.
+- Tell the user: _"I've loaded the SMS setup guide. It will walk you through configuring Twilio, handling compliance requirements, and testing SMS delivery."_
 
 The sms-setup skill handles: Twilio credential storage (Account SID + Auth Token), phone number provisioning or assignment, public ingress setup, SMS compliance verification, and end-to-end test sending. Once SMS is set up, messaging is available automatically — no additional feature flag is needed.
 
@@ -86,10 +88,9 @@ The sms-setup skill also includes optional **guardian verification** for SMS, wh
 
 ### Guardian Verification (SMS, Voice, or Telegram)
 
-If the user asks to verify their guardian identity for any channel (SMS, voice, or Telegram), install and load the **guardian-verify-setup** skill:
+If the user asks to verify their guardian identity for any channel (SMS, voice, or Telegram), load the **guardian-verify-setup** skill:
 
-- Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "guardian-verify-setup"`.
-- Then call `skill_load` with `skill: "guardian-verify-setup"`.
+- Call `skill_load` with `skill_id: "guardian-verify-setup"` to load the dependency skill.
 
 The guardian-verify-setup skill handles the full outbound verification flow for all supported channels. It collects the user's destination (phone number or Telegram chat ID/handle), initiates an outbound verification session, and guides the user through entering or replying with the verification code. This is the single source of truth for guardian verification setup -- do not duplicate the verification flow inline.
 
@@ -107,11 +108,12 @@ When a messaging tool fails with a token or authorization error:
 - If the user specifies a platform (e.g., "check my Slack"), pass it as the `platform` parameter.
 - If only one platform is connected, it is auto-selected.
 - If multiple platforms are connected and the user doesn't specify, ask which platform they mean — or search across all of them.
-- **Be action-oriented with email.** When the user says "email" and wants to *do* something (declutter, check, search, send), check what's connected first. If nothing is connected, ask which provider briefly and then go straight into setup — don't present menus, options lists, or explain the setup process. Just do it.
+- **Be action-oriented with email.** When the user says "email" and wants to _do_ something (declutter, check, search, send), check what's connected first. If nothing is connected, ask which provider briefly and then go straight into setup — don't present menus, options lists, or explain the setup process. Just do it.
 
 ## Capabilities
 
 ### Universal (Slack, Gmail)
+
 - **Auth Test**: Verify connection and show account info
 - **List Conversations**: Show channels, inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
@@ -121,40 +123,48 @@ When a messaging tool fails with a token or authorization error:
 - **Mark Read**: Mark conversation as read
 
 ### Telegram
+
 Telegram is supported as a messaging provider with limited capabilities compared to Slack and Gmail due to Bot API constraints:
 
 - **Send**: Send a message to a known chat ID (high risk — requires user approval)
 - **Auth Test**: Verify bot token and show bot info
 
 **Not available** (Bot API limitations):
+
 - List conversations — the Bot API does not expose a method to enumerate chats a bot belongs to
 - Read message history — bots cannot retrieve past messages from a chat
 - Search messages — no search API is available for bots
 
 **Bot-account limits:**
+
 - The bot can only message users or groups that have previously interacted with it (sent `/start` or been added to a group). Bots cannot initiate conversations with arbitrary phone numbers.
 - Future support for MTProto user-account sessions may lift some of these restrictions.
 
 ### SMS (Twilio)
+
 SMS is supported as a messaging provider with limited capabilities. The conversation ID is the recipient's phone number in E.164 format (e.g. `+14155551234`):
 
 - **Send**: Send an SMS to a phone number (high risk — requires user approval)
 - **Auth Test**: Verify Twilio credentials and show the configured phone number
 
 **Not available** (SMS limitations):
+
 - List conversations — SMS is stateless; there is no API to enumerate past conversations
 - Read message history — message history is not available through the gateway
 - Search messages — no search API is available for SMS
 
 **SMS limits:**
+
 - Outbound SMS uses the assistant's configured Twilio phone number as the sender. The phone number must be provisioned and assigned via the twilio-setup skill.
 - SMS messages are subject to Twilio's character limits and carrier filtering. Long messages may be split into multiple segments.
 
 ### Slack-specific
+
 - **Add Reaction**: Add an emoji reaction to a message
 - **Leave Channel**: Leave a Slack channel
 
 ### Gmail-specific
+
 - **Archive**: Remove message from inbox
 - **Label**: Add/remove labels
 - **Trash**: Move to trash
@@ -162,6 +172,7 @@ SMS is supported as a messaging provider with limited capabilities. The conversa
 - **Draft (native)**: Create a draft in Gmail's Drafts folder
 
 ### Attachments (Gmail)
+
 - **List Attachments**: `gmail_list_attachments` — list all attachments on a message with filename, MIME type, size, and attachment ID
 - **Download Attachment**: `gmail_download_attachment` — download an attachment to the working directory by message ID + attachment ID
 - **Send with Attachments**: `gmail_send_with_attachments` — send an email with file attachments (reads files from disk, builds multipart MIME)
@@ -169,21 +180,25 @@ SMS is supported as a messaging provider with limited capabilities. The conversa
 Workflow: use `gmail_list_attachments` to discover attachments, then `gmail_download_attachment` to save them locally.
 
 ### Forward & Thread Operations (Gmail)
+
 - **Forward**: `gmail_forward` — forward a message to another recipient, preserving all attachments. Optionally prepend your own text
 - **Summarize Thread**: `gmail_summarize_thread` — LLM-powered thread summary with participants, decisions, open questions, and sentiment
 - **Follow-up Tracking**: `gmail_follow_up` — track/untrack messages for follow-up using a dedicated "Follow-up" label, or list all tracked messages
 
 ### Smart Triage (Gmail)
+
 - **Triage**: `gmail_triage` — LLM-powered inbox classification of unread emails into categories: `needs_reply`, `fyi_only`, `can_archive`, `urgent`, `newsletter`, `promotional`
   - Returns grouped report with reasoning and suggested actions per email
   - Set `auto_apply: true` to auto-archive `can_archive` emails and label `needs_reply` as "Follow-up"
   - Custom query support (default: `is:unread in:inbox`)
 
 ### Inbox Automation (Gmail)
+
 - **Filters**: `gmail_filters` — list, create, or delete Gmail filters. Filter criteria include from, to, subject, query, has_attachment. Actions include adding/removing labels and forwarding
 - **Vacation Responder**: `gmail_vacation` — get, enable, or disable the vacation auto-responder with custom message, date range, and domain/contact restrictions
 
 ### Google Contacts
+
 - **Contacts**: `google_contacts` — list or search Google Contacts by name or email. Returns name, email, phone, and organization
   - Requires the `contacts.readonly` scope — users may need to re-authorize Gmail to grant this additional permission
 
@@ -191,30 +206,30 @@ Workflow: use `gmail_list_attachments` to discover attachments, then `gmail_down
 
 When searching Slack, the query is passed directly to Slack's search API:
 
-| Operator | Example | What it finds |
-|---|---|---|
-| `from:` | `from:@alice` | Messages from a specific user |
-| `in:` | `in:#general` | Messages in a specific channel |
-| `has:` | `has:link` | Messages containing links |
-| `before:` | `before:2024-01-01` | Messages before a date |
-| `after:` | `after:2024-01-01` | Messages after a date |
-| `has:reaction` | `has:reaction` | Messages with reactions |
-| `has:star` | `has:star` | Starred messages |
+| Operator       | Example             | What it finds                  |
+| -------------- | ------------------- | ------------------------------ |
+| `from:`        | `from:@alice`       | Messages from a specific user  |
+| `in:`          | `in:#general`       | Messages in a specific channel |
+| `has:`         | `has:link`          | Messages containing links      |
+| `before:`      | `before:2024-01-01` | Messages before a date         |
+| `after:`       | `after:2024-01-01`  | Messages after a date          |
+| `has:reaction` | `has:reaction`      | Messages with reactions        |
+| `has:star`     | `has:star`          | Starred messages               |
 
 ## Gmail Search Syntax
 
 When searching Gmail, the query uses Gmail's search operators:
 
-| Operator | Example | What it finds |
-|---|---|---|
-| `from:` | `from:alice@example.com` | Messages from a specific sender |
-| `to:` | `to:bob@example.com` | Messages sent to a recipient |
-| `subject:` | `subject:meeting` | Messages with a word in the subject |
-| `newer_than:` | `newer_than:7d` | Messages from the last 7 days |
-| `older_than:` | `older_than:30d` | Messages older than 30 days |
-| `is:unread` | `is:unread` | Unread messages |
-| `has:attachment` | `has:attachment` | Messages with attachments |
-| `label:` | `label:work` | Messages with a specific label |
+| Operator         | Example                  | What it finds                       |
+| ---------------- | ------------------------ | ----------------------------------- |
+| `from:`          | `from:alice@example.com` | Messages from a specific sender     |
+| `to:`            | `to:bob@example.com`     | Messages sent to a recipient        |
+| `subject:`       | `subject:meeting`        | Messages with a word in the subject |
+| `newer_than:`    | `newer_than:7d`          | Messages from the last 7 days       |
+| `older_than:`    | `older_than:30d`         | Messages older than 30 days         |
+| `is:unread`      | `is:unread`              | Unread messages                     |
+| `has:attachment` | `has:attachment`         | Messages with attachments           |
+| `label:`         | `label:work`             | Messages with a specific label      |
 
 ## Drafting vs Sending
 
@@ -253,9 +268,11 @@ Use `messaging_analyze_activity` to classify channels or conversations by activi
 
 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_batch_archive`, `gmail_archive_by_query`, `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.
+
 ### Provider Selection
 
-- **Gmail connected**: Use the Gmail-specific tools (`gmail_sender_digest`, `gmail_archive_by_query`, `gmail_unsubscribe`, `gmail_filters`) — they have richer features like unsubscribe support and filter creation.
+- **Gmail connected**: Use the Gmail-specific tools (`gmail_sender_digest`, `gmail_batch_archive`, `gmail_unsubscribe`, `gmail_filters`) — they have richer features like unsubscribe support and filter creation.
 - **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) — they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
 - **Nothing connected**: Ask which email provider they use. If it's Gmail, go straight into the Gmail connection flow. For other providers, let the user know only Gmail is supported right now and offer to set up Gmail instead. Don't present a menu of options or explain what OAuth is.
 
@@ -269,14 +286,14 @@ When a user asks to declutter, clean up, or organize their email — start scann
    - **Caption**: "Showing emails from last 90 days in Promotions" (or adjusted to match the query used)
    - **Gmail action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
    - **Non-Gmail action button (exactly 1)**: "Archive Selected" (primary). Do not offer an unsubscribe button — it is Gmail-specific. **NEVER offer Delete, Trash, or any destructive action.**
-3. **Live progress**: After the user clicks an action button:
+3. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button:
    - **Dismiss the table immediately** with `ui_dismiss` — it collapses to a completion chip
    - **Show a `task_progress` card** with one step per selected sender (e.g., "Archiving TechCrunch (247 emails)"). Update each step from `in_progress` → `completed` as each sender finishes.
    - When all senders are processed, set the progress card's `status: "completed"`.
 4. **Act on selection**: For each selected sender:
-   - Use `gmail_archive_by_query` (or `messaging_archive_by_sender` for non-Gmail) with the sender's `search_query` — this archives all matching messages in one call, regardless of volume
+   - Use `gmail_batch_archive` (or `messaging_archive_by_sender` for non-Gmail) with the sender's `message_ids` array — this archives exactly the messages that were scanned and counted
    - If Gmail and the action is "Archive & Unsubscribe" and `has_unsubscribe` is true, call `gmail_unsubscribe` with the sender's `newest_message_id`
-5. **Accurate summary**: Use the **actual counts returned by the archive tool**, not the scan counts from the digest. The scan is a sample; the archive is comprehensive. Format: "Cleaned up [total_archived] emails from [sender_count] senders." For Gmail, append: "Unsubscribed from [unsub_count]."
+5. **Accurate summary**: The scan counts are exact — the `message_count` shown in the table matches the number of `message_ids` that were archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders." For Gmail, append: "Unsubscribed from [unsub_count]."
 6. **Ongoing protection offer (Gmail only)**: After reporting results, offer auto-archive filters:
    - "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"
    - If yes, call `gmail_filters` with `action: "create"` for each sender with `from` set to the sender's email and `remove_label_ids: ["INBOX"]`.
@@ -286,7 +303,7 @@ When a user asks to declutter, clean up, or organize their email — start scann
 
 - **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
-- **Large sender counts**: The `has_more` flag indicates a sender had more messages than collected — `gmail_archive_by_query` handles this automatically via its own pagination
+- **Large sender counts**: The scan covers up to 2000 messages. If `truncated` is true in the top-level response, the scan was capped and there are more matching emails beyond what was scanned — tell the user the cleanup was partial and offer to run another pass. If `has_more` is true for a sender, it means they had more messages than could be tracked — mention this to the user in the summary
 
 ## Batch Operations
 

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

@@ -221,96 +221,6 @@
       "executor": "tools/messaging-mark-read.ts",
       "execution_target": "host"
     },
-    {
-      "name": "slack_add_reaction",
-      "description": "Add an emoji reaction to a Slack message. Include a confidence score (0-1).",
-      "category": "messaging",
-      "risk": "medium",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "channel": {
-            "type": "string",
-            "description": "Slack channel ID"
-          },
-          "timestamp": {
-            "type": "string",
-            "description": "Message timestamp (ts)"
-          },
-          "emoji": {
-            "type": "string",
-            "description": "Emoji name without colons (e.g. \"thumbsup\")"
-          },
-          "confidence": {
-            "type": "number",
-            "description": "Confidence score (0-1) for this action"
-          }
-        },
-        "required": [
-          "channel",
-          "timestamp",
-          "emoji",
-          "confidence"
-        ]
-      },
-      "executor": "tools/slack-add-reaction.ts",
-      "execution_target": "host"
-    },
-    {
-      "name": "slack_delete_message",
-      "description": "Delete a Slack message posted by the bot. Include a confidence score (0-1).",
-      "category": "messaging",
-      "risk": "high",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "channel": {
-            "type": "string",
-            "description": "Slack channel ID"
-          },
-          "timestamp": {
-            "type": "string",
-            "description": "Message timestamp (ts) to delete"
-          },
-          "confidence": {
-            "type": "number",
-            "description": "Confidence score (0-1) for this action"
-          }
-        },
-        "required": [
-          "channel",
-          "timestamp",
-          "confidence"
-        ]
-      },
-      "executor": "tools/slack-delete-message.ts",
-      "execution_target": "host"
-    },
-    {
-      "name": "slack_leave_channel",
-      "description": "Leave a Slack channel. Include a confidence score (0-1).",
-      "category": "messaging",
-      "risk": "medium",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "channel": {
-            "type": "string",
-            "description": "Slack channel ID to leave"
-          },
-          "confidence": {
-            "type": "number",
-            "description": "Confidence score (0-1) for this action"
-          }
-        },
-        "required": [
-          "channel",
-          "confidence"
-        ]
-      },
-      "executor": "tools/slack-leave-channel.ts",
-      "execution_target": "host"
-    },
     {
       "name": "messaging_analyze_activity",
       "description": "Analyze channel or conversation activity levels. Groups conversations as high/medium/low/dead activity.",
@@ -1006,11 +916,15 @@
           },
           "max_messages": {
             "type": "number",
-            "description": "Maximum messages to scan (default 500, cap 2000)"
+            "description": "Maximum messages to scan (default 2000, cap 2000)"
           },
           "max_senders": {
             "type": "number",
             "description": "Maximum senders to return (default 30)"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Resume token from a previous scan's next_page_token to continue scanning beyond the cap"
           }
         }
       },
@@ -1035,11 +949,15 @@
           },
           "max_messages": {
             "type": "number",
-            "description": "Maximum messages to scan (default 500, cap 2000)"
+            "description": "Maximum messages to scan (default 2000, cap 2000)"
           },
           "max_senders": {
             "type": "number",
             "description": "Maximum senders to return (default 30)"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Resume token from a previous scan's next_page_token to continue scanning beyond the cap"
           }
         }
       },
@@ -1098,6 +1016,10 @@
           "min_confidence": {
             "type": "number",
             "description": "Minimum confidence threshold 0-1 (default 0.5)"
+          },
+          "page_token": {
+            "type": "string",
+            "description": "Resume token from a previous scan's next_page_token to continue scanning beyond the cap"
           }
         }
       },