@vellumai/assistant 0.4.55 → 0.4.57

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

@@ -6,52 +6,58 @@ metadata:
   emoji: "\U0001F4AC"
   vellum:
     display-name: "Messaging"
-    user-invocable: true
+    activation-hints:
+      - "Email, messaging, inbox management, read/send/search on any platform"
+      - "Handles credential flows -- do not improvise setup instructions"
 ---
 
 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.
 
+## External Identity
+
+When composing messages on behalf of your user to external recipients, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+
 For Gmail management (archive, label, triage, declutter), load the **gmail** skill. For email sequences, load the **sequences** skill.
 
 ## 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.
 
-When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally — never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
+When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally - never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
 
 ## Connection Setup
 
 Before using any messaging tool, verify that the platform is connected by calling `messaging_auth_test` with the appropriate `platform` parameter. If the call fails with a token/authorization error, follow the steps below.
 
-### Public Ingress (required for Slack and Telegram)
+### Public Ingress (required for Telegram)
 
-Slack and Telegram setup require a publicly reachable URL for OAuth callbacks or webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-applescript skill) handles public ingress internally when needed.
+Telegram setup requires a publicly reachable URL for webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Slack uses Socket Mode and does not require public ingress. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-applescript skill) handles public ingress internally when needed.
 
 ### Email Connection Flow
 
-When the user asks to "connect my email", "set up email", "manage my email", or similar — and has not named a specific provider:
+When the user asks to "connect my email", "set up email", "manage my email", or similar - and has not named a specific provider:
 
 1. **Discover what's connected.** Call `messaging_auth_test` for `gmail` (and any other email-capable platforms). If one succeeds, tell the user it's already connected and proceed with their request.
-2. **If nothing is connected**, ask which provider they use — but keep it brief and conversational (e.g., "Which email do you use — Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
+2. **If nothing is connected**, ask which provider they use - but keep it brief and conversational (e.g., "Which email do you use - Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
 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.
+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.
@@ -59,16 +65,12 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 
 ### 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. Load the **slack-oauth-setup** skill:
-   - Call `skill_load` with `skill: "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."
-     - **confirmLabel:** "Get Started"
-     - **cancelLabel:** "Not Now"
-   - Wait for the user to confirm before proceeding with the setup guide. If they decline, acknowledge and let them know they can set it up later.
-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.
+Slack connects via Socket Mode using a bot token and app-level token (not OAuth). Load the **slack-app-setup** skill, which guides the user through creating a Slack app from a pre-configured manifest, collecting tokens securely, and connecting the bot to their workspace:
+
+- Call `skill_load` with `skill: "slack-app-setup"` to load the dependency skill.
+- Tell the user Slack isn't connected yet and briefly explain what the setup involves, then follow the skill's guided flow.
+
+The slack-app-setup skill handles: manifest-driven app creation, app token and bot token collection via secure prompt (never accept tokens pasted in plaintext chat), and Slack connection setup through the same settings handler used by the Settings UI. That handler validates the bot token, stores workspace metadata, and activates Socket Mode. The skill also covers optional guardian verification.
 
 ### Telegram
 
@@ -77,7 +79,7 @@ Telegram uses a bot token (not OAuth). Load the **telegram-setup** skill (which
 - Call `skill_load` with `skill: "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 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.
 
@@ -94,7 +96,7 @@ The guardian-verify-setup skill handles the full outbound verification flow for
 When a messaging tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and the appropriate `service`. 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 that platform (e.g., install and load **google-oauth-applescript** for Gmail). 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 that platform (e.g., install and load **google-oauth-applescript** for Gmail). 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 messaging 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.
 
@@ -102,8 +104,8 @@ 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.
+- 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.
 
 ## Capabilities
 
@@ -113,21 +115,21 @@ When a messaging tool fails with a token or authorization error:
 - **List Conversations**: Show channels, inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
 - **Search**: Search messages with platform-appropriate query syntax
-- **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk — requires user approval.
+- **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk - requires user approval.
 - **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)
+- **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
+- 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:**
 
@@ -138,10 +140,10 @@ Telegram is supported as a messaging provider with limited capabilities compared
 
 - **Add Reaction**: Add an emoji reaction to a message
 - **Leave Channel**: Leave a Slack channel
-- **Edit Message**: `slack_edit_message` — edit a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`) from the original send response. High risk — requires confidence score.
-- **Delete Message**: `slack_delete_message` — delete a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`). High risk — requires confidence score. This is irreversible.
+- **Edit Message**: `slack_edit_message` - edit a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`) from the original send response. High risk - requires confidence score.
+- **Delete Message**: `slack_delete_message` - delete a message the assistant previously sent. Requires `channel_id` and the message timestamp (`ts`). High risk - requires confidence score. This is irreversible.
 
-When sending a Slack message, retain the `ts` (message timestamp) from the send response — it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
+When sending a Slack message, retain the `ts` (message timestamp) from the send response - it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
 
 ## Slack Search Syntax
 
@@ -185,7 +187,7 @@ Medium and high risk tools require a confidence score between 0 and 1:
 When a user asks to declutter, clean up, or organize their email:
 
 - **Gmail connected**: Load the **gmail** skill, which has the full decluttering workflow with `gmail_sender_digest`, `gmail_archive`, `gmail_unsubscribe`, and `gmail_filters`.
-- **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.
+- **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.
 
 ### Non-Gmail Decluttering Workflow
@@ -193,7 +195,7 @@ When a user asks to declutter, clean up, or organize their email:
 1. **Scan**: Call `messaging_sender_digest`. Default query targets promotions from the last 90 days.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
    - **Columns (exactly 2)**: Sender, Emails Found
-   - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
+   - **Pre-select all rows** (`selected: true`) - users deselect what they want to keep
    - **Caption**: Data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep."
    - **Action button (exactly 1)**: "Archive Selected" (primary). **NEVER offer Delete, Trash, or any destructive action.**
 3. **Wait for user action**: Stop and wait. Do NOT proceed until the user clicks the action button.

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

@@ -17,7 +17,7 @@
             "type": "string",
             "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -54,7 +54,7 @@
             "type": "number",
             "description": "Maximum number of conversations to return (default 200)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -91,7 +91,7 @@
             "type": "number",
             "description": "Maximum number of messages to return (default 50)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -125,7 +125,7 @@
             "type": "number",
             "description": "Maximum number of results to return (default 20)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -182,7 +182,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"
           }
@@ -216,7 +216,7 @@
             "type": "string",
             "description": "Specific message ID to mark as read (optional)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -250,7 +250,7 @@
             "type": "string",
             "description": "Optional search filter (e.g. 'to:alice@example.com' for Gmail, 'from:@me' for Slack)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -276,10 +276,6 @@
             "type": "string",
             "description": "Platform (e.g. \"slack\", \"gmail\"). Required for create/list."
           },
-          "account": {
-            "type": "string",
-            "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
-          },
           "conversation_id": {
             "type": "string",
             "description": "Target conversation/channel ID (for create)"
@@ -300,7 +296,7 @@
             "type": "string",
             "description": "Draft ID (for delete)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -340,9 +336,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"
           }
@@ -375,7 +371,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"
           }

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -58,7 +58,7 @@ export async function run(
     // Gmail: create a draft instead of sending directly
     if (provider.id === "gmail") {
       const gmailConn = conn as OAuthConnection;
-      // Reply mode: thread_id provided — create a threaded draft with reply-all recipients
+      // Reply mode: thread_id provided - create a threaded draft with reply-all recipients
       if (threadId) {
         // Fetch thread messages to extract recipients and threading headers
         const list = await listMessages(gmailConn, `thread:${threadId}`, 10);

package/src/config/bundled-skills/messaging/tools/shared.ts

@@ -130,7 +130,7 @@ export async function resolveProvider(
  * for the given messaging provider.
  *
  * Non-OAuth providers (e.g. Telegram) use isConnected() and don't need
- * tokens — they receive an empty string which the string overload handles.
+ * tokens - they receive an empty string which the string overload handles.
  */
 export async function getProviderConnection(
   provider: MessagingProvider,

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

@@ -6,7 +6,6 @@ metadata:
   emoji: "🔔"
   vellum:
     display-name: "Notifications"
-    user-invocable: true
 ---
 
 Use `send_notification` for user-facing alerts and notifications. This tool routes through the unified notification pipeline, which handles channel selection, delivery, deduplication, and audit logging.
@@ -18,21 +17,21 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 
 ## Deduplication (`dedupe_key`)
 
-- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused — any future notification with the same key will be silently discarded.
+- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused - any future notification with the same key will be silently discarded.
 - Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
 - If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
 
-## Threading
+## Conversation Grouping
 
-Thread grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to thread X" parameter — thread reuse is inferred, not commanded.
+Conversation grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to conversation X" parameter - conversation reuse is inferred, not commanded.
 
-**How it works:** The engine evaluates recent notification thread candidates and decides whether a new signal is a continuation of an existing thread based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies — the engine groups by semantic relatedness, not string matching.
+**How it works:** The engine evaluates recent notification conversation candidates and decides whether a new signal is a continuation of an existing conversation based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies - the engine groups by semantic relatedness, not string matching.
 
 **`source_event_name` is the primary grouping signal.** Use a stable event name for notifications that belong to the same logical stream (e.g. `dog.news.thread.reply` for all replies in a thread). Use a distinct event name when the notification represents a genuinely different kind of event.
 
 **Practical constraints:**
 
-- Thread candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old thread from days ago.
+- Conversation candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old conversation from days ago.
 - The engine will only reuse conversations originally created by the notification system (`source === 'notification'`). It will never append to a user-initiated conversation, even if it looks related.
 
 ## Important

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "send_notification",
-      "description": "Send a notification through the unified notification router. The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
+      "description": "Send an immediate notification. Fires instantly with no delay capability. For one-time future alerts, use schedule_create with fire_at. For recurring alerts, use schedule_create with expression (cron/RRULE). The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
       "category": "notifications",
       "risk": "medium",
       "input_schema": {
@@ -48,7 +48,7 @@
           },
           "conversation_id": {
             "type": "string",
-            "description": "Optional source conversation/session ID for notification context"
+            "description": "Optional source conversation ID for notification context"
           },
           "source_event_name": {
             "type": "string",
@@ -66,7 +66,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"
           }

package/src/config/bundled-skills/notifications/tools/send-notification.ts

@@ -110,14 +110,14 @@ export async function run(
     asNonEmptyString(input.source_event_name) ?? "user.send_notification";
   const requestedConversationId =
     asNonEmptyString(input.conversation_id) ?? context.conversationId;
-  const sourceSessionId = requestedConversationId ?? context.sessionId;
+  const sourceContextId = requestedConversationId ?? context.conversationId;
   const title = asNonEmptyString(input.title);
   const dedupeKey = asNonEmptyString(input.dedupe_key);
 
   const contextPayload: Record<string, unknown> = {
     requestedMessage: message,
     requestedByTool: "send_notification",
-    requestedBySessionId: context.sessionId,
+    requestedByContextId: context.conversationId,
   };
   if (title) contextPayload.requestedTitle = title;
   if (requestedConversationId)
@@ -130,7 +130,7 @@ export async function run(
     await emitNotificationSignal({
       sourceEventName,
       sourceChannel: "assistant_tool",
-      sourceSessionId,
+      sourceContextId,
       attentionHints: {
         requiresAction: parseBool(input.requires_action, true),
         urgency,

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

@@ -6,7 +6,10 @@ metadata:
   emoji: "\U0001F500"
   vellum:
     display-name: "Orchestration"
-    user-invocable: true
+    activation-hints:
+      - "Multiple independent work streams that benefit from parallel execution"
+    avoid-when:
+      - "Single-focus tasks -- work directly"
 ---
 
 Use `swarm_delegate` when facing complex multi-part tasks that benefit from parallel execution. The tool decomposes an objective into independent specialist subtasks, runs them concurrently, and synthesises the results.
@@ -19,7 +22,7 @@ Use `swarm_delegate` when facing complex multi-part tasks that benefit from para
 
 ## When NOT to use
 
-- Simple single-step requests — just do them directly.
+- Simple single-step requests - just do them directly.
 - Tasks that are inherently sequential (each step depends on the previous result).
 - Requests where the user is asking for a quick answer, not a deep workflow.
 

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

@@ -21,7 +21,7 @@
             "type": "number",
             "description": "Maximum concurrent workers (1-6, default from config)"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of what you are doing and why, shown to the user as a status update. Use simple language a non-technical person would understand."
           }

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -1,20 +1,28 @@
 ---
 name: phone-calls
-description: Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist
+description: "Make outgoing phone calls, receive incoming calls, and pull up past call transcripts"
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "📞"
   vellum:
     display-name: "Phone Calls"
-    user-invocable: true
     includes:
       - "twilio-setup"
       - "public-ingress"
       - "elevenlabs-voice"
+    activation-hints:
+      - "Phone calling setup, Twilio config, placing/receiving calls"
+      - "Do NOT improvise Twilio setup from general knowledge"
+    avoid-when:
+      - "Don't confuse with voice-setup (local PTT/mic) or guardian-verify-setup"
 ---
 
 You are helping the user set up and manage phone calls via Twilio. This skill covers enabling the calls feature, placing outbound calls, receiving inbound calls, and interacting with live calls. Twilio credential storage, phone number provisioning, and public ingress are handled by the **twilio-setup** skill.
 
+## External Identity
+
+When speaking on behalf of your user during calls, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+
 # Overview
 
 The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls with **ElevenLabs** providing the text-to-speech voice. After Twilio setup, the assistant configures ElevenLabs as the TTS provider and prompts the user to choose a voice from a curated list of supported options.
@@ -51,24 +59,32 @@ Before making real calls, offer a quick verification. Suggest a test call to the
 
 If they agree, ask for their personal phone number and place a test call with a simple task like "Introduce yourself and confirm the call system is working."
 
-## Step 5: Guardian Verification (Optional)
+## Step 5: Guardian Verification
+
+The final step is for the user to verify themselves so that they are recognized when they call you. It's also a great way for them to hear what you sound like and decide if they want you to use a different voice.
 
-By going through Guardian Verification, the user will be recognized any time they call the assistant and will be able to interact with the assistant with elevated privileges. You should encourage the user to go through the guardian verification process, but not force it.
+Load the `guardian-verify-setup` skill and follow the instructions for guardian verification over the `phone` channel. This will require the user to provide you with their phone number and then for you to give them a call. Say something like:
 
-Load the `guardian-verify-setup` skill with `channel: "phone"`. The skill handles the full verification flow (outbound call, code entry, confirmation).
+> Want to do a quick verification call now so that you can hear what I sound like and also so that I recognize your number when you call me in the future?
+> I'll show a 6 digit code here in the chat and when you answer my call, enter it using your phone's keypad.
 
-If the user declines, skip this step. To re-check guardian status later:
+You can check their verification status with:
 
 ```bash
 assistant channel-verification-sessions status --channel phone --json
 ```
 
+After they are verified, ask them what they think of your voice and offer to let them change it. Load up the `elevenlabs-voice` skill and follow the instructions there to see what voices are available and how to update your configured voice. Say something like:
+
+> Great, you're verified! What did you think of my voice? We can update it if you'd like.
+
+
 # Making Outbound Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
 
 - **phone_number**: The number to call in E.164 format (e.g. `+14155551234`)
-- **task**: What the call should accomplish — this becomes the AI voice agent's objective
+- **task**: What the call should accomplish - this becomes the AI voice agent's objective
 - **context** (optional): Additional background information for the conversation
 
 ### Example calls:
@@ -132,7 +148,7 @@ Once Twilio is configured and the assistant has a phone number, inbound calls wo
 
 1. The gateway resolves the assistant by phone number and forwards to the runtime
 2. A new voice session is created, keyed by the Twilio CallSid
-3. The LLM-driven orchestrator answers in receptionist mode — greeting the caller warmly and asking how it can help
+3. The LLM-driven orchestrator answers in receptionist mode - greeting the caller warmly and asking how it can help
 4. The conversation proceeds naturally, with ASK_GUARDIAN dispatches to consult the user when needed
 
 No additional configuration is needed beyond Twilio setup and `calls.enabled` being `true`. As long as the phone number has been provisioned/assigned, inbound calls are handled automatically.
@@ -150,7 +166,7 @@ During an active call, the user can interact with the AI voice agent via the HTT
 When the AI voice agent encounters something it needs user input for, it dispatches an **ASK_GUARDIAN** request to all configured guardian channels (mac desktop, Telegram). The call status changes to `waiting_on_user`.
 
 1. The question is delivered simultaneously to every configured channel. The first channel to respond wins (first-response-wins semantics) -- once one channel provides an answer, the other channels receive a "already answered" notice.
-2. On the mac desktop, a guardian request thread is created with the question. On Telegram, the question text and a request code are delivered via the gateway.
+2. On the mac desktop, a guardian request conversation is created with the question. On Telegram, the question text and a request code are delivered via the gateway.
 3. If DTMF callee verification is enabled, the callee must enter a verification code before the call proceeds (see the **DTMF Callee Verification** section above).
 4. The guardian provides an answer through whichever channel they prefer. The answer is routed to the AI voice agent, which continues the conversation naturally.
 
@@ -173,7 +189,7 @@ The follow-up flow works across all guardian channels. The guardian can receive
 
 #### Steering with instructions
 
-When there is **no pending question** but the call is still active, the user can send steering instructions via the HTTP API (`POST /v1/calls/:id/instruction`) to proactively guide the call in real time — for example:
+When there is **no pending question** but the call is still active, the user can send steering instructions via the HTTP API (`POST /v1/calls/:id/instruction`) to proactively guide the call in real time - for example:
 
 - "Ask them about their cancellation policy too"
 - "Wrap up the call, we have what we need"
@@ -182,17 +198,17 @@ When there is **no pending question** but the call is still active, the user can
 
 The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly.
 
-**Note:** Steering is done via the HTTP API, not the desktop chat thread. The desktop thread only receives pointer/status messages about the call.
+**Note:** Steering is done via the HTTP API, not the desktop chat conversation. The desktop conversation only receives pointer/status messages about the call.
 
 ### Call status values
 
-- **initiated** — Call is being placed
-- **ringing** — Phone is ringing on the other end
-- **in_progress** — Call is connected, conversation is active
-- **waiting_on_user** — AI agent needs input from the user (check pending question)
-- **completed** — Call ended successfully
-- **failed** — Call failed (check lastError for details)
-- **cancelled** — Call was manually cancelled
+- **initiated** - Call is being placed
+- **ringing** - Phone is ringing on the other end
+- **in_progress** - Call is connected, conversation is active
+- **waiting_on_user** - AI agent needs input from the user (check pending question)
+- **completed** - Call ended successfully
+- **failed** - Call failed (check lastError for details)
+- **cancelled** - Call was manually cancelled
 
 ### Ending a call early
 
@@ -206,6 +222,6 @@ call_end call_session_id="<session_id>" reason="User requested to end the call"
 
 For detailed information on the following topics, see the reference files:
 
-- **[Retrieving Past Call Transcripts](references/TRANSCRIPTS.md)** — How to find and query full bidirectional call transcripts from the database
-- **[Configuration Reference & Call Quality Tips](references/CONFIG.md)** — All call-related config settings, defaults, and tips for writing effective call tasks
-- **[Troubleshooting](references/TROUBLESHOOTING.md)** — Common error messages, connectivity issues, and debugging steps
+- **[Retrieving Past Call Transcripts](references/TRANSCRIPTS.md)** - How to find and query full bidirectional call transcripts from the database
+- **[Configuration Reference & Call Quality Tips](references/CONFIG.md)** - All call-related config settings, defaults, and tips for writing effective call tasks
+- **[Troubleshooting](references/TROUBLESHOOTING.md)** - Common error messages, connectivity issues, and debugging steps

package/src/config/bundled-skills/phone-calls/TOOLS.json

@@ -26,7 +26,7 @@
             "enum": ["assistant_number", "user_number"],
             "description": "Which phone number to use as the caller ID. assistant_number uses the AI assistant's Twilio number; user_number uses the user's verified personal number."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -48,7 +48,7 @@
             "type": "string",
             "description": "Specific call session ID to check. If omitted, checks for an active call in the current conversation."
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
@@ -74,7 +74,7 @@
             "type": "string",
             "description": "Reason for ending the call"
           },
-          "reason": {
+          "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }

package/src/config/bundled-skills/phone-calls/references/CONFIG.md

@@ -44,13 +44,13 @@ When crafting tasks for the AI voice agent, follow these guidelines for the best
 ## Writing good task descriptions
 
 - **Be specific about the objective**: "Make a dinner reservation for 2 at 7pm tonight" is better than "Call the restaurant"
-- **Include relevant context**: Names, account numbers, appointment details — anything the agent might need
+- **Include relevant context**: Names, account numbers, appointment details - anything the agent might need
 - **Specify what information to collect**: "Ask about their return policy and store hours" tells the agent what to gather
 - **Set clear completion criteria**: The agent knows to end the call when the task is fulfilled
 
 ## Providing context
 
-The `context` field is powerful — use it to give the agent background that helps it sound natural:
+The `context` field is powerful - use it to give the agent background that helps it sound natural:
 
 - User's name and identifying details (for making appointments, verifying accounts)
 - Preferences and constraints (dietary restrictions, budget limits, scheduling conflicts)