@vellumai/assistant 0.4.56 → 0.5.0

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -3,18 +3,18 @@
   "tools": [
     {
       "name": "computer_use_observe",
-      "description": "Capture the current screen state. Returns the accessibility tree with [ID] element references and optionally a screenshot.\n\nThe accessibility tree shows interactive elements like [3] AXButton 'Save' or [17] AXTextField 'Search'. Use element_id to target these elements in subsequent actions — this is much more reliable than pixel coordinates.\n\nCall this before your first computer use action, or to check screen state without acting.",
+      "description": "Capture the current screen state. Returns the accessibility tree with [ID] element references and optionally a screenshot.\n\nThe accessibility tree shows interactive elements like [3] AXButton 'Save' or [17] AXTextField 'Search'. Use element_id to target these elements in subsequent actions - this is much more reliable than pixel coordinates.\n\nCall this before your first computer use action, or to check screen state without acting.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
         "type": "object",
         "properties": {
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["reason"]
+        "required": ["activity"]
       },
       "executor": "tools/computer-use-observe.ts",
       "execution_target": "host"
@@ -48,7 +48,7 @@
             "type": "string",
             "description": "Explanation of what you see and why you are clicking here"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -74,7 +74,7 @@
             "type": "string",
             "description": "Explanation of what you are typing and why"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -100,7 +100,7 @@
             "type": "string",
             "description": "Explanation of why you are pressing this key"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -143,7 +143,7 @@
             "type": "string",
             "description": "Explanation of why you are scrolling"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -189,7 +189,7 @@
             "type": "string",
             "description": "Explanation of what you are dragging and why"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -215,7 +215,7 @@
             "type": "string",
             "description": "Explanation of what you are waiting for"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -227,7 +227,7 @@
     },
     {
       "name": "computer_use_open_app",
-      "description": "Open or switch to a macOS application by name. Preferred over cmd+tab for switching apps \u2014 more reliable and explicit.",
+      "description": "Open or switch to a macOS application by name. Preferred over cmd+tab for switching apps - more reliable and explicit.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -241,7 +241,7 @@
             "type": "string",
             "description": "Explanation of why you need to open or switch to this app"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -253,7 +253,7 @@
     },
     {
       "name": "computer_use_run_applescript",
-      "description": "Run an AppleScript command. Prefer this over click/type when possible \u2014 it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
+      "description": "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -267,7 +267,7 @@
             "type": "string",
             "description": "Explanation of what this script does and why AppleScript is better than UI interaction for this step"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -289,7 +289,7 @@
             "type": "string",
             "description": "Human-readable summary of what was accomplished"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -315,7 +315,7 @@
             "type": "string",
             "description": "Explanation of how you determined the answer"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

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

@@ -291,7 +291,7 @@ If the user provides a phone number without the `+` country code prefix, ask the
 
 ### Create an email invite
 
-Use this when the guardian wants to invite someone to message the assistant via email. Email invites use a 6-digit code — the invitee sends the code to the assistant's email address to redeem access.
+Use this when the guardian wants to invite someone to message the assistant via email. Email invites use a 6-digit code - the invitee sends the code to the assistant's email address to redeem access.
 
 ```bash
 assistant contacts invites create --source-channel email --contact-id "<contact_id>" --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
@@ -322,7 +322,7 @@ If the assistant's email address is not available (AgentMail not configured), te
 
 ### Create a WhatsApp invite
 
-Use this when the guardian wants to invite someone to message the assistant on WhatsApp. WhatsApp invites use a 6-digit code — the invitee sends the code to the assistant's WhatsApp number to redeem access.
+Use this when the guardian wants to invite someone to message the assistant on WhatsApp. WhatsApp invites use a 6-digit code - the invitee sends the code to the assistant's WhatsApp number to redeem access.
 
 ```bash
 assistant contacts invites create --source-channel whatsapp --contact-id "<contact_id>" --contact-name "<invitee_name>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json
@@ -443,7 +443,7 @@ Replace `<invite_id>` with the invite's `id` from the list response. The same re
 
 ## Google Contacts
 
-Use `google_contacts` to list or search the user's Google Contacts by name or email. Returns name, email, phone, and organization. Requires the `contacts.readonly` OAuth scope — users may need to re-authorize Gmail to grant this additional permission.
+Use `google_contacts` to list or search the user's Google Contacts by name or email. Returns name, email, phone, and organization. Requires the `contacts.readonly` OAuth scope - users may need to re-authorize Gmail to grant this additional permission.
 
 ## Contact Fields
 

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

@@ -52,7 +52,7 @@
               "required": ["type", "address"]
             }
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -86,7 +86,7 @@
             "type": "number",
             "description": "Maximum results to return (default 20, max 100)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -112,7 +112,7 @@
             "type": "string",
             "description": "ID of the contact to merge into the kept contact (will be deleted)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -147,7 +147,7 @@
             "type": "string",
             "description": "Pagination token (for list)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },

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

@@ -1,6 +1,6 @@
 ---
 name: document
-description: Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides). Use when the user says write, draft, compose, or create a blog/article/essay.
+description: Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides)
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "📄"
@@ -12,14 +12,14 @@ Create and edit long-form documents using the built-in rich text editor. Documen
 
 ## Tools
 
-- **document_create** — Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
-- **document_update** — Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
+- **document_create** - Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
+- **document_update** - Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
 
 ## Workflow
 
 1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, *italic*, code blocks, tables, lists, blockquotes as appropriate.
-3. **CRITICAL — Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
+3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
 4. **Respond to edits**: When the user requests changes via the docked chat, use `document_update` with `replace` for full rewrites or `append` for additions.
 
 ## Usage Notes

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

@@ -17,7 +17,7 @@
             "type": "string",
             "description": "Initial Markdown content to populate the editor (optional)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -47,7 +47,7 @@
             "enum": ["replace", "append"],
             "description": "Whether to replace all content or append to the end. Defaults to append."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

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

@@ -29,7 +29,7 @@
             "type": "string",
             "description": "Optional recurrence schedule ID to fire a reminder when overdue"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -64,7 +64,7 @@
             "type": "boolean",
             "description": "When true, return only pending follow-ups past their expected response deadline"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -94,7 +94,7 @@
             "type": "string",
             "description": "Conversation ID to match (used with channel for auto-resolution)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

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

@@ -1,6 +1,6 @@
 ---
 name: gmail
-description: Archive, label, draft, unsubscribe, and manage Gmail with smart inbox tools
+description: Archive, label, draft, unsubscribe, and manage Gmail
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "📨"
@@ -8,31 +8,31 @@ metadata:
     display-name: "Gmail"
 ---
 
-This skill provides Gmail-specific tools. For cross-platform messaging (send, read, search, reply), use the **messaging** skill. Gmail tools depend on the messaging skill's provider infrastructure — load messaging first if Gmail is not yet connected.
+This skill provides Gmail-specific tools. For cross-platform messaging (send, read, search, reply), use the **messaging** skill. Gmail tools depend on the messaging skill's provider infrastructure - load messaging first if Gmail is not yet connected.
 
 ## 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 AgentMail 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 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.
 
 ## Communication Style
 
-- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox — that's obviously what they want.
-- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" — not "the OAuth2 access token for integration:google has expired."
+- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.
+- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" - not "the OAuth2 access token for integration:google has expired."
 - **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
-- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do — just do it and narrate lightly.
+- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do - just do it and narrate lightly.
 
 ## Connection Setup
 
 ### 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.
+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. Load the **google-oauth-applescript** skill:
    - Call `skill_load` with `skill: "google-oauth-applescript"` 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 few pages in your browser and walk you through setting up Google Cloud credentials — creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
+     - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
      - **confirmLabel:** "Get Started"
      - **cancelLabel:** "Not Now"
    - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
@@ -43,7 +43,7 @@ Do not offer AgentMail as an option or mention it unless the user specifically a
 When a Gmail tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected — let me set that up") and immediately follow the connection setup flow for Gmail (e.g., install and load **google-oauth-applescript**). The user came to you to get something done, not to troubleshoot OAuth — make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for Gmail (e.g., install and load **google-oauth-applescript**). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the Gmail tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 
@@ -59,20 +59,20 @@ When a Gmail tool fails with a token or authorization error:
 
 ### Attachments
 
-- **Attachments**: `gmail_attachments` — list or download Gmail attachments. Use `action: "list"` to enumerate attachments on a message (returns filename, MIME type, size, and attachment ID), then `action: "download"` with `attachment_id` and `filename` to save a specific attachment to disk.
-- **Send with Attachments**: `messaging_send` with `attachment_paths` — create a Gmail draft with file attachments (reads files from disk, builds multipart MIME)
+- **Attachments**: `gmail_attachments` - list or download Gmail attachments. Use `action: "list"` to enumerate attachments on a message (returns filename, MIME type, size, and attachment ID), then `action: "download"` with `attachment_id` and `filename` to save a specific attachment to disk.
+- **Send with Attachments**: `messaging_send` with `attachment_paths` - create a Gmail draft with file attachments (reads files from disk, builds multipart MIME)
 
 Workflow: use `gmail_attachments` with `action: "list"` to discover attachments, then `gmail_attachments` with `action: "download"` to save them locally.
 
 ### Forward & Thread Operations
 
-- **Forward**: `gmail_forward` — forward a message to another recipient, preserving all attachments. Optionally prepend your own text
-- **Follow-up Tracking**: `gmail_follow_up` — track/untrack messages for follow-up using a dedicated "Follow-up" label, or list all tracked messages
+- **Forward**: `gmail_forward` - forward a message to another recipient, preserving all attachments. Optionally prepend your own text
+- **Follow-up Tracking**: `gmail_follow_up` - track/untrack messages for follow-up using a dedicated "Follow-up" label, or list all tracked messages
 
 ### Inbox Automation
 
-- **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
+- **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
 
 ## Drafting vs Sending (Gmail)
 
@@ -92,7 +92,7 @@ Gmail uses a **draft-first workflow**. All compose and reply tools create Gmail
 
 When replying to or continuing an email thread:
 
-- Use `messaging_send` with the thread's `thread_id` — it automatically handles threading, reply-all recipients, and subject lines.
+- Use `messaging_send` with the thread's `thread_id` - it automatically handles threading, reply-all recipients, and subject lines.
 - The `in_reply_to` field on `gmail_draft` requires the **RFC 822 Message-ID header** (looks like `<CABx...@mail.gmail.com>`), NOT the Gmail message ID (which looks like `18e4a5b2c3d4e5f6`). Get it by reading the thread messages and extracting the `Message-ID` header.
 
 ## Gmail Search Syntax
@@ -112,9 +112,9 @@ When searching Gmail, the query uses Gmail's search operators:
 
 ## Email Decluttering
 
-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.
+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, 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.
 
 ### Workflow
 
@@ -122,17 +122,17 @@ When a user asks to declutter, clean up, or organize their email — start scann
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
    - **Columns (exactly 3)**: Sender, Emails Found, Unsub?
      - **Unsub? cell values**: Use rich cell format: `{ "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" }` when `has_unsubscribe` is true, `{ "text": "No", "icon": "minus.circle", "iconColor": "muted" }` when false.
-   - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
-   - **Caption**: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) the Unsub? column legend: "Unsub? — \"Yes\" means these emails contain an unsubscribe link, so I can opt you out automatically. \"No\" means no unsubscribe link was found — these will be archived but you may continue receiving them."
+   - **Pre-select all rows** (`selected: true`) - users deselect what they want to keep
+   - **Caption**: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) the Unsub? column legend: "Unsub? - \"Yes\" means these emails contain an unsubscribe link, so I can opt you out automatically. \"No\" means no unsubscribe link was found - these will be archived but you may continue receiving them."
    - **Action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
 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
+   - **Dismiss the table immediately** with `ui_dismiss` - it collapses to a completion chip
    - **Show a `task_progress` card** with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step from `in_progress` → `completed` as each phase finishes.
    - When all senders are processed, set the progress card's `status: "completed"`.
-4. **Act on selection** — batch, don't loop:
-   - **Archive all at once**: Call `gmail_archive` **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the Gmail API calls internally — never loop sender-by-sender.
-   - **Unsubscribe in bulk**: If the action is "Archive & Unsubscribe", call `gmail_unsubscribe` for each sender that has `has_unsubscribe: true` — but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
-5. **Accurate summary**: The scan counts are exact — the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
+4. **Act on selection** - batch, don't loop:
+   - **Archive all at once**: Call `gmail_archive` **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the Gmail API calls internally - never loop sender-by-sender.
+   - **Unsubscribe in bulk**: If the action is "Archive & Unsubscribe", call `gmail_unsubscribe` for each sender that has `has_unsubscribe: true` - but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
+5. **Accurate summary**: The scan counts are exact - the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
 6. **Ongoing protection offer**: 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"]`.
@@ -142,21 +142,21 @@ 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
-- **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 - 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.
 
 ## 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` is a pure data aggregation tool - it finds senders without List-Unsubscribe headers (potential cold outreach) and does not use LLM classification.
 
 - 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** - if archiving fails with an expiration error, re-run the scan
 - Raw `message_ids` still work as a fallback for non-scan workflows
 
 ## Batch Operations
 
 - `gmail_archive` supports `scan_id` + `sender_ids` (preferred for declutter workflows) or raw `message_ids`.
-- `gmail_label` supports `message_id` or `message_ids` only — it does not accept `scan_id`.
+- `gmail_label` supports `message_id` or `message_ids` only - it does not accept `scan_id`.
 - First scan to get a `scan_id`, then use `gmail_archive` to batch-archive by sender.
 - Always confirm with the user before batch operations on large numbers of messages.
 
@@ -164,7 +164,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 `<temporal_context>` block in the current turn for today's date and upcoming dates
+1. Check the `<temporal_context>` block in the current turn 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 temporal context to ensure it's in the future
 

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

@@ -39,7 +39,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -90,7 +90,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -120,7 +120,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -150,7 +150,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -196,7 +196,7 @@
             "type": "string",
             "description": "BCC recipients (comma-separated email addresses)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -226,7 +226,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -265,7 +265,7 @@
             "type": "string",
             "description": "Filename to save as (required for download)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -303,7 +303,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -338,7 +338,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -411,7 +411,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -466,7 +466,7 @@
             "type": "number",
             "description": "Confidence score (0-1) for this action"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -502,9 +502,9 @@
           },
           "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 10,000 messages in a single call)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },
@@ -519,7 +519,7 @@
     },
     {
       "name": "gmail_outreach_scan",
-      "description": "Scan Gmail inbox for senders without List-Unsubscribe headers (potential cold outreach). Returns top senders with message counts and sample subjects. Read-only — use gmail_archive and gmail_filters for cleanup.",
+      "description": "Scan Gmail inbox for senders without List-Unsubscribe headers (potential cold outreach). Returns top senders with message counts and sample subjects. Read-only - use gmail_archive and gmail_filters for cleanup.",
       "category": "gmail",
       "risk": "low",
       "input_schema": {
@@ -539,9 +539,9 @@
           },
           "page_token": {
             "type": "string",
-            "description": "Resume token from a previous scan (rarely needed — scans now cover up to 5,000 messages in a single call)"
+            "description": "Resume token from a previous scan (rarely needed - scans now cover up to 5,000 messages in a single call)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           },

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

@@ -124,7 +124,7 @@ export async function run(
 
   // Batch path for scan_id+sender_ids and message_ids
   if (!messageIds?.length) {
-    return err("Resolved message list is empty — no messages to archive.");
+    return err("Resolved message list is empty - no messages to archive.");
   }
 
   try {

package/src/config/bundled-skills/gmail/tools/gmail-sender-digest.ts

@@ -171,7 +171,7 @@ export async function run(
         agg.hasMore = true;
       }
 
-      // Track date range — compare using internalDate (epoch ms) for reliability
+      // Track date range - compare using internalDate (epoch ms) for reliability
       const msgEpoch = msg.internalDate ? Number(msg.internalDate) : 0;
       const oldestEpoch = agg.oldestDate
         ? new Date(agg.oldestDate).getTime()

package/src/config/bundled-skills/google-calendar/SKILL.md

@@ -17,7 +17,7 @@ Before using any Calendar tool, verify that Google Calendar is connected by atte
 1. **Do NOT call `credential_store oauth2_connect` yourself.** You do not have valid OAuth client credentials, and fabricating a client_id will cause a "401: invalid_client" error from Google.
 2. Instead, load the **google-oauth-applescript** skill, which walks the user through creating real credentials in Google Cloud Console:
    - Call `skill_load` with `skill: "google-oauth-applescript"` to load the dependency skill.
-3. Tell the user: _"Google Calendar isn't connected yet. I've loaded a setup guide that will walk you through connecting your Google account — it only takes a couple of minutes."_
+3. Tell the user: _"Google Calendar isn't connected yet. I've loaded a setup guide that will walk you through connecting your Google account - it only takes a couple of minutes."_
 
 ## Capabilities