@vellumai/assistant 0.4.29 → 0.4.30

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

@@ -2,7 +2,7 @@
 name: "Notifications"
 description: "Send notifications through the unified notification router"
 user-invocable: true
-metadata: {"vellum": {"emoji": "\ud83d\udd14"}}
+metadata: { "vellum": { "emoji": "\ud83d\udd14" } }
 ---
 
 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.
@@ -27,10 +27,11 @@ Thread grouping is handled by the LLM-powered decision engine, not by any parame
 **`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.
 - 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
 
 - Do **NOT** use AppleScript `display notification` or other OS-level notification commands for assistant-managed alerts. Always use `send_notification`.
-- For sending messages into a specific chat, email, or SMS destination, use the messaging skill's `messaging_send` instead.
+- For sending rich content (digests, summaries, reports) to a specific chat, email, or SMS destination, use the messaging skill's `messaging_send` instead. The decision engine rewrites `send_notification` content into short alerts, which strips rich formatting.

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

@@ -19,11 +19,7 @@
           },
           "urgency": {
             "type": "string",
-            "enum": [
-              "low",
-              "medium",
-              "high"
-            ],
+            "enum": ["low", "medium", "high"],
             "description": "Urgency hint (default: \"medium\")"
           },
           "requires_action": {
@@ -46,10 +42,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "enum": [
-                "vellum",
-                "telegram"
-              ]
+              "enum": ["vellum", "telegram", "slack"]
             },
             "description": "Optional routing hints for preferred channels (not deterministic)"
           },
@@ -72,12 +65,13 @@
           "confidence": {
             "type": "number",
             "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": [
-          "message",
-          "confidence"
-        ]
+        "required": ["message", "confidence"]
       },
       "executor": "tools/send-notification.ts",
       "execution_target": "host"

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

@@ -25,6 +25,10 @@
             "type": "string",
             "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": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["phone_number", "task"]
@@ -43,6 +47,10 @@
           "call_session_id": {
             "type": "string",
             "description": "Specific call session ID to check. If omitted, checks for an active call in the current conversation."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": []
@@ -62,9 +70,13 @@
             "type": "string",
             "description": "The call session ID to end"
           },
-          "reason": {
+          "end_reason": {
             "type": "string",
             "description": "Reason for ending the call"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["call_session_id"]

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

@@ -33,6 +33,10 @@
           "priority": {
             "type": "number",
             "description": "Relative priority \u2014 higher numbers take precedence. Defaults to 0."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["trigger", "action"]
@@ -55,6 +59,10 @@
           "category": {
             "type": "string",
             "description": "Filter by category (e.g. \"scheduling\", \"triage\"). Omit to show all."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         }
       },
@@ -97,6 +105,10 @@
           "priority": {
             "type": "number",
             "description": "Updated priority"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["playbook_id"]
@@ -115,6 +127,10 @@
           "playbook_id": {
             "type": "string",
             "description": "ID of the playbook to delete (from playbook_list results)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["playbook_id"]

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "reminder_create",
-      "description": "Create a one-time time-based reminder. Reminders fire at a specific future time and either notify the user or execute a message through the assistant. Use this ONLY when the user wants a time-triggered notification (e.g. \"remind me at 3pm\", \"remind me in 2 hours\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" — use task_list_add for those requests.",
+      "description": "Create a one-time time-based reminder. Reminders fire at a specific future time and either notify the user or execute a message through the assistant. Use this ONLY when the user wants a time-triggered notification (e.g. \"remind me at 3pm\", \"remind me in 2 hours\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" \u2014 use task_list_add for those requests.",
       "category": "reminder",
       "risk": "low",
       "input_schema": {
@@ -34,6 +34,10 @@
           "routing_hints": {
             "type": "object",
             "description": "Optional hints for the routing engine (e.g. preferred channels, exclusions)."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["fire_at", "label", "message"]
@@ -48,7 +52,12 @@
       "risk": "low",
       "input_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
         "required": []
       },
       "executor": "tools/reminder-list.ts",
@@ -65,6 +74,10 @@
           "reminder_id": {
             "type": "string",
             "description": "Reminder ID to cancel"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["reminder_id"]

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

@@ -1,7 +1,7 @@
 ---
 name: "Schedule"
 description: "Recurring automation that dispatches messages on a cron or RRULE schedule"
-metadata: {"vellum": {"emoji": "\ud83d\udcc5"}}
+metadata: { "vellum": { "emoji": "\ud83d\udcc5" } }
 ---
 
 Manage recurring scheduled automations. Each schedule has an expression (cron or RRULE) that defines when it fires, and a message that gets dispatched to the assistant at trigger time.
@@ -12,15 +12,16 @@ Manage recurring scheduled automations. Each schedule has an expression (cron or
 
 Standard 5-field cron syntax: `minute hour day-of-month month day-of-week`
 
-| Field         | Values        | Special characters |
-|---------------|---------------|--------------------|
-| Minute        | 0-59          | , - * /            |
-| Hour          | 0-23          | , - * /            |
-| Day of month  | 1-31          | , - * /            |
-| Month         | 1-12          | , - * /            |
-| Day of week   | 0-7 (0,7=Sun) | , - * /            |
+| Field        | Values        | Special characters |
+| ------------ | ------------- | ------------------ |
+| Minute       | 0-59          | , - \* /           |
+| Hour         | 0-23          | , - \* /           |
+| Day of month | 1-31          | , - \* /           |
+| Month        | 1-12          | , - \* /           |
+| Day of week  | 0-7 (0,7=Sun) | , - \* /           |
 
 Examples:
+
 - `0 9 * * 1-5` — weekdays at 9:00 AM
 - `30 8 * * *` — every day at 8:30 AM
 - `0 */2 * * *` — every 2 hours
@@ -32,26 +33,29 @@ iCalendar recurrence rules for complex patterns. Must include a DTSTART line.
 
 Supported lines (all expressions must include DTSTART + at least one RRULE or RDATE):
 
-| Line | Purpose |
-|------|---------|
-| `DTSTART` | Start date/time anchor (required) |
-| `RRULE:` | Recurrence rule (multiple lines = union of occurrences) |
-| `RDATE` | Add one-off dates not covered by the pattern |
-| `EXDATE` | Exclude specific dates from the set |
-| `EXRULE` | Exclude an entire recurring series |
+| Line      | Purpose                                                 |
+| --------- | ------------------------------------------------------- |
+| `DTSTART` | Start date/time anchor (required)                       |
+| `RRULE:`  | Recurrence rule (multiple lines = union of occurrences) |
+| `RDATE`   | Add one-off dates not covered by the pattern            |
+| `EXDATE`  | Exclude specific dates from the set                     |
+| `EXRULE`  | Exclude an entire recurring series                      |
 
 Exclusions (EXDATE, EXRULE) always take precedence over inclusions (RRULE, RDATE).
 
 #### Basic examples
+
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY` — every day at 9:00 AM UTC
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR` — Mon/Wed/Fri at 9:00 AM UTC
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1,15` — 1st and 15th of each month
 
 #### Bounded recurrence
+
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY;COUNT=30` — daily for 30 occurrences then stop
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO;UNTIL=20250331T235959Z` — every Monday until end of March
 
 #### Set construct examples
+
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\nEXDATE:20250120T090000Z` — Mon/Wed/Fri except Jan 20
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY\nEXRULE:FREQ=WEEKLY;BYDAY=SA,SU` — every weekday (daily minus weekends)
 - `DTSTART:20250101T090000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1\nRDATE:20250704T090000Z` — 1st of each month plus July 4th
@@ -86,6 +90,20 @@ When `schedule_create` returns, it includes an integration status summary. Cross
 - If the task involves a **multi-step workflow** (e.g., book appointment → read confirmation email), trace the full dependency chain
 
 If any required capability is missing:
+
 1. **Do NOT tell the user the schedule is ready** — instead, explain what's missing and why the schedule won't work yet
 2. Offer to help set up the missing integration first
 3. The schedule is still created (so timing is preserved), but make it clear it won't execute successfully until dependencies are resolved
+
+## Delivering Results
+
+Scheduled messages run without user interaction. If the task produces output that the user should see (e.g. a digest, summary, or report), the scheduled message **must** include an explicit instruction to deliver the results. Without this, the output only lives in the conversation log and never reaches the user.
+
+Choose the right delivery tool based on the content:
+
+- **Rich content** (digests, summaries, reports): Use `messaging_send` with the target platform and conversation ID. This preserves the full content and posts directly.
+- **Short alerts** (status updates, completion notices): Use `send_notification` to let the notification router pick the best channel. Note: the router's decision engine rewrites content into short alerts, so it is not suitable for rich content.
+
+Example schedule message for a Slack digest:
+
+> "Scan my Slack channels for the last 24 hours using slack_scan_digest, then use messaging_send with platform 'slack' and conversation_id 'C0A7STRJ4G5' to post the summary to #alex-agent-messages."

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "schedule_create",
-      "description": "Create a recurring scheduled automation that sends a message at a cron or RRULE interval. ONLY use this when the user explicitly wants something to run on a schedule (e.g. \"every day at 9am\", \"weekly on Mondays\", \"every hour\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" — use task_list_add for those requests instead.",
+      "description": "Create a recurring scheduled automation that sends a message at a cron or RRULE interval. ONLY use this when the user explicitly wants something to run on a schedule (e.g. \"every day at 9am\", \"weekly on Mondays\", \"every hour\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" \u2014 use task_list_add for those requests instead.",
       "category": "schedule",
       "risk": "medium",
       "input_schema": {
@@ -37,6 +37,10 @@
           "enabled": {
             "type": "boolean",
             "description": "Whether the job is enabled immediately. Defaults to true."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["name", "message"]
@@ -59,6 +63,10 @@
           "job_id": {
             "type": "string",
             "description": "If provided, show detailed info and recent runs for this specific job."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": []
@@ -106,6 +114,10 @@
           "enabled": {
             "type": "boolean",
             "description": "Enable or disable the job"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["job_id"]
@@ -124,6 +136,10 @@
           "job_id": {
             "type": "string",
             "description": "The ID of the schedule to delete"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["job_id"]

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

@@ -2,7 +2,7 @@
 name: "Slack"
 description: "Scan channels, summarize threads, and manage Slack with privacy guardrails"
 user-invocable: true
-metadata: {"vellum": {"emoji": "💬"}}
+metadata: { "vellum": { "emoji": "💬" } }
 ---
 
 You are a Slack assistant that helps users stay on top of their Slack workspace. Use the slack tools for channel scanning, thread summarization, and Slack-specific operations.
@@ -40,6 +40,35 @@ Use `slack_configure_channels` to save and load preferred channels for scanning.
 - After a first scan, suggest configuring defaults: "Want me to remember these channels for future scans?"
 - Saved preferences are used automatically by `slack_scan_digest` when no specific channels are requested
 
+## Channel Permissions
+
+Use `slack_channel_permissions` to manage per-channel permission profiles. These profiles control which tools are available and what trust level applies in specific Slack channels.
+
+- **list**: Show all configured channel permission profiles
+- **get**: View the permission profile for a specific channel
+- **set**: Configure permissions for a channel (allowed tool categories, blocked tools, trust level)
+- **remove**: Remove a channel's permission profile
+- **clear**: Remove all permission profiles
+
+When a channel has a "restricted" trust level, exercise additional caution with tool usage. Blocked tools and category restrictions are enforced automatically when processing messages from that channel.
+
+## Thread-Aware Conversations
+
+When responding to messages from Slack channels, replies are automatically threaded. The assistant tracks conversation-to-thread mappings so that:
+
+- Replies to a channel message go to the correct Slack thread
+- Continuing a conversation stays in the same thread
+- Thread context expires after 24 hours of inactivity, starting a fresh thread
+
+## Proactive Delivery
+
+When you need to **send** content to Slack proactively (e.g. a scheduled digest, a scan summary, or a report):
+
+- Use `messaging_send` with `platform: "slack"` and the target `conversation_id` (Slack channel or DM ID). This posts directly via `chat.postMessage` and preserves the full message content.
+- Do **NOT** use `send_notification` for rich content like digests — the notification router's decision engine rewrites content into short alerts, stripping the actual digest.
+- `send_notification` is appropriate for short alerts and status updates where you want the router to pick the best channel. `messaging_send` is appropriate when you have specific content to deliver to a specific Slack destination.
+- For scheduled tasks (cron/RRULE), always end with a `messaging_send` call so the results actually reach the user. Without it, the output only lives in the conversation log.
+
 ## Watcher Integration
 
 For real-time monitoring (not just on-demand scanning), the user can set up a Slack watcher using the watcher skill with the same channel IDs. Mention this if the user wants ongoing monitoring.

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

@@ -11,7 +11,9 @@
         "properties": {
           "channel_ids": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Specific channel IDs to scan. If omitted, scans preferred or top active channels."
           },
           "hours_back": {
@@ -25,6 +27,15 @@
           "max_channels": {
             "type": "number",
             "description": "Maximum number of channels to scan (default 20)"
+          },
+          "format": {
+            "type": "string",
+            "enum": ["text", "blocks"],
+            "description": "Output format: 'text' returns JSON (default), 'blocks' returns Slack Block Kit structured output"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         }
       },
@@ -42,6 +53,10 @@
           "channel_id": {
             "type": "string",
             "description": "The Slack channel ID to get details for"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel_id"]
@@ -64,8 +79,14 @@
           },
           "channel_ids": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Channel IDs to add, remove, or set (not needed for 'list')"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["action"]
@@ -96,6 +117,10 @@
           "confidence": {
             "type": "number",
             "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel", "timestamp", "emoji", "confidence"]
@@ -122,6 +147,10 @@
           "confidence": {
             "type": "number",
             "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel", "timestamp", "confidence"]
@@ -152,6 +181,10 @@
           "confidence": {
             "type": "number",
             "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel", "timestamp", "text", "confidence"]
@@ -174,12 +207,66 @@
           "confidence": {
             "type": "number",
             "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel", "confidence"]
       },
       "executor": "tools/slack-leave-channel.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "slack_channel_permissions",
+      "description": "Manage per-channel permission profiles for Slack channels. Configure which tools are available, set trust levels, and manage permission overrides on a per-channel basis.",
+      "category": "slack",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["list", "get", "set", "remove", "clear"],
+            "description": "Action to perform: list all profiles, get a specific channel's profile, set a channel's profile, remove a channel's profile, or clear all profiles"
+          },
+          "channel_id": {
+            "type": "string",
+            "description": "Slack channel ID (required for get, set, remove)"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable label for this channel's permission set (for 'set' action)"
+          },
+          "allowed_tool_categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tool categories allowed in this channel. When set, only tools in these categories can be invoked (for 'set' action)"
+          },
+          "blocked_tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Specific tool names blocked in this channel (for 'set' action)"
+          },
+          "trust_level": {
+            "type": "string",
+            "enum": ["restricted", "standard"],
+            "description": "Trust level override: 'restricted' limits tool access, 'standard' uses defaults (for 'set' action)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["action"]
+      },
+      "executor": "tools/slack-channel-permissions.ts",
+      "execution_target": "host"
     }
   ]
 }