@vellumai/assistant 0.3.0

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

@@ -0,0 +1,20 @@
+---
+name: "Reminder"
+description: "One-time time-based reminders that fire at a specific future time"
+metadata: {"vellum": {"emoji": "🔔"}}
+---
+
+Create, list, and cancel one-time reminders. Reminders fire at a specific future time and either notify the user or execute a message through the assistant.
+
+## Modes
+
+- **notify** (default) — shows a notification to the user when the reminder fires
+- **execute** — sends the reminder message to a background assistant conversation for autonomous handling
+
+## Usage Notes
+
+- Use reminders ONLY for time-triggered notifications (e.g. "remind me at 3pm", "remind me in 2 hours").
+- For recurring automation, use schedules instead.
+- For task tracking ("add to my tasks", "add to my queue"), use task_list_add instead.
+- `fire_at` must be a strict ISO 8601 timestamp with timezone offset or Z (e.g. `2025-03-15T09:00:00-05:00` or `2025-03-15T09:00:00Z`). Ambiguous timestamps without timezone info will be rejected.
+- `label` is a short human-readable summary shown in the notification.

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

@@ -0,0 +1,67 @@
+{
+  "version": 1,
+  "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.",
+      "category": "reminder",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "fire_at": {
+            "type": "string",
+            "description": "ISO 8601 timestamp for when the reminder should fire"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable label"
+          },
+          "message": {
+            "type": "string",
+            "description": "Content shown in notification (notify) or sent to agent (execute)"
+          },
+          "mode": {
+            "type": "string",
+            "enum": ["notify", "execute"],
+            "description": "How the reminder fires. Defaults to notify."
+          }
+        },
+        "required": ["fire_at", "label", "message"]
+      },
+      "executor": "tools/reminder-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "reminder_list",
+      "description": "List all reminders and their current status.",
+      "category": "reminder",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      },
+      "executor": "tools/reminder-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "reminder_cancel",
+      "description": "Cancel a pending reminder by ID.",
+      "category": "reminder",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "reminder_id": {
+            "type": "string",
+            "description": "Reminder ID to cancel"
+          }
+        },
+        "required": ["reminder_id"]
+      },
+      "executor": "tools/reminder-cancel.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/reminder/tools/reminder-cancel.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeReminderCancel } from '../../../../tools/reminder/reminder.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeReminderCancel(input);
+}

package/src/config/bundled-skills/reminder/tools/reminder-create.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeReminderCreate } from '../../../../tools/reminder/reminder.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeReminderCreate(input);
+}

package/src/config/bundled-skills/reminder/tools/reminder-list.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeReminderList } from '../../../../tools/reminder/reminder.js';
+
+export async function run(
+  _input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeReminderList();
+}

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

@@ -0,0 +1,74 @@
+---
+name: "Schedule"
+description: "Recurring automation that dispatches messages on a cron or RRULE schedule"
+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.
+
+## Schedule Syntax
+
+### Cron
+
+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) | , - * /            |
+
+Examples:
+- `0 9 * * 1-5` — weekdays at 9:00 AM
+- `30 8 * * *` — every day at 8:30 AM
+- `0 */2 * * *` — every 2 hours
+- `0 9 1 * *` — first of every month at 9:00 AM
+
+### RRULE (RFC 5545)
+
+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 |
+
+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
+- `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=TU\nRRULE:FREQ=WEEKLY;BYDAY=TH` — union of Tuesdays and Thursdays
+
+## Tool Input
+
+Use `syntax` + `expression` to specify the schedule type explicitly, or just `expression` to auto-detect. The legacy `cron_expression` field is still accepted as a cron alias.
+
+## Lifecycle
+
+1. Create a schedule with a name, expression, and message.
+2. At each trigger time, the message is dispatched to the assistant as if the user sent it.
+3. Schedules can be enabled/disabled, updated, or deleted.
+
+## Tips
+
+- Only use `schedule_create` when the user explicitly wants recurring automation (e.g. "every day at 9am", "weekly on Mondays"). For one-time tasks, use the task list instead.
+- Timezones default to the system timezone if omitted. Use IANA timezone identifiers (e.g. "America/Los_Angeles").
+- Prefer RRULE for complex patterns that cron cannot express (e.g. "every other Tuesday", "last weekday of the month").

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

@@ -0,0 +1,135 @@
+{
+  "version": 1,
+  "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.",
+      "category": "schedule",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "A human-readable name for the scheduled task"
+          },
+          "syntax": {
+            "type": "string",
+            "enum": ["cron", "rrule"],
+            "description": "Schedule syntax type. Auto-detected if omitted."
+          },
+          "expression": {
+            "type": "string",
+            "description": "Canonical schedule expression (cron or RRULE). Preferred over cron_expression."
+          },
+          "cron_expression": {
+            "type": "string",
+            "description": "Deprecated alias for expression with cron syntax. Use expression + syntax instead."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone (e.g. \"America/Los_Angeles\"). Defaults to system timezone if omitted."
+          },
+          "message": {
+            "type": "string",
+            "description": "The message to send to the assistant when the schedule triggers"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the job is enabled immediately. Defaults to true."
+          }
+        },
+        "required": ["name", "message"]
+      },
+      "executor": "tools/schedule-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "schedule_list",
+      "description": "List recurring scheduled automations (cron jobs or RRULE schedules), or show details and recent runs for a specific one. For the user's task queue, use task_list_show instead.",
+      "category": "schedule",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "enabled_only": {
+            "type": "boolean",
+            "description": "When true, only show enabled jobs. Defaults to false."
+          },
+          "job_id": {
+            "type": "string",
+            "description": "If provided, show detailed info and recent runs for this specific job."
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/schedule-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "schedule_update",
+      "description": "Update an existing recurring scheduled automation (expression, syntax, message, name, or enabled state)",
+      "category": "schedule",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "job_id": {
+            "type": "string",
+            "description": "The ID of the schedule to update"
+          },
+          "name": {
+            "type": "string",
+            "description": "New name for the job"
+          },
+          "syntax": {
+            "type": "string",
+            "enum": ["cron", "rrule"],
+            "description": "Schedule syntax type. Auto-detected if omitted."
+          },
+          "expression": {
+            "type": "string",
+            "description": "New schedule expression (cron or RRULE). Preferred over cron_expression."
+          },
+          "cron_expression": {
+            "type": "string",
+            "description": "Deprecated alias for expression with cron syntax. Use expression + syntax instead."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "New IANA timezone"
+          },
+          "message": {
+            "type": "string",
+            "description": "New message to send when triggered"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Enable or disable the job"
+          }
+        },
+        "required": ["job_id"]
+      },
+      "executor": "tools/schedule-update.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "schedule_delete",
+      "description": "Delete a recurring scheduled automation and all its run history",
+      "category": "schedule",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "job_id": {
+            "type": "string",
+            "description": "The ID of the schedule to delete"
+          }
+        },
+        "required": ["job_id"]
+      },
+      "executor": "tools/schedule-delete.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/schedule/tools/schedule-create.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeScheduleCreate } from '../../../../tools/schedule/create.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeScheduleCreate(input, context);
+}

package/src/config/bundled-skills/schedule/tools/schedule-delete.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeScheduleDelete } from '../../../../tools/schedule/delete.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeScheduleDelete(input, context);
+}

package/src/config/bundled-skills/schedule/tools/schedule-list.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeScheduleList } from '../../../../tools/schedule/list.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeScheduleList(input, context);
+}

package/src/config/bundled-skills/schedule/tools/schedule-update.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeScheduleUpdate } from '../../../../tools/schedule/update.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeScheduleUpdate(input, context);
+}

package/src/config/bundled-skills/self-upgrade/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: "Self Upgrade"
+description: "Upgrade vellum to the latest version, restart the daemon, and restart the gateway"
+user-invocable: true
+metadata: {"vellum": {"emoji": "⬆️"}}
+---
+
+You are performing a self-upgrade of the Vellum assistant. Follow these steps **in order**. Use the `bash` tool to run each command. Confirm each step succeeds before moving to the next.
+
+## Step 1: Record the current version
+
+```bash
+vellum --version
+```
+
+Save this value to report later.
+
+## Step 2: Install the latest vellum
+
+```bash
+bun install -g vellum@latest
+```
+
+After updating, verify the new version:
+
+```bash
+vellum --version
+```
+
+## Step 3: Restart the gateway
+
+If a gateway process is running, restart it so it picks up any protocol or dependency changes from the new version:
+
+```bash
+pgrep -f 'vellum-gateway|gateway/src/index.ts' || echo "No gateway process found"
+```
+
+If a gateway PID is found, send it SIGTERM so it drains gracefully:
+
+```bash
+pkill -TERM -f 'vellum-gateway|gateway/src/index.ts'
+```
+
+Then start the gateway again using whatever method the user's deployment uses (e.g. `bun run gateway/src/index.ts`, a systemd service, or a container orchestrator). If you are unsure how the gateway is deployed, ask the user.
+
+## Step 4: Restart the daemon
+
+Use `vellum daemon restart` which stops the old daemon and starts a new one from the updated binary in a single command:
+
+```bash
+vellum daemon restart
+```
+
+Verify it is running:
+
+```bash
+vellum daemon status
+```
+
+**Important:** This is the last step because the current daemon process is the one executing this conversation. After the restart, the new daemon takes over and this session ends gracefully.
+
+## After Upgrade
+
+Report back to the user with:
+- The previous and new vellum version
+- Daemon status (running, PID)
+- Gateway status (restarted or not found)
+- Any errors encountered during the process

package/src/config/bundled-skills/start-the-day/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: "Start the Day"
+description: "Get a personalized daily briefing with weather, news, and actionable insights"
+user-invocable: true
+metadata: {"vellum": {"emoji": "🌅"}}
+---
+
+You are a personal daily briefing assistant. When the user invokes this skill, generate a concise, actionable briefing tailored to the current moment.
+
+## Briefing Structure
+
+Build the briefing in sections. Use what you know about the user and their context to decide which sections are relevant. Don't include sections you have nothing useful to say about.
+
+### 1. Weather & Conditions
+
+Check the user's location (from system context or ask once) and provide:
+- Current conditions and temperature
+- High/low for the day
+- Notable weather (rain, extreme temps, wind) — only if it affects plans
+
+### 2. Top Headlines
+
+Summarize 3-5 notable news items. Prioritize:
+- Stories relevant to the user's interests or industry
+- Major world events
+- Tech/product launches if relevant
+- Keep each to one sentence
+
+### 3. Calendar & Meetings
+
+If you have access to calendar context:
+- List today's meetings with times
+- Flag any prep needed (documents to review, talking points)
+- Note gaps that could be used for focused work
+
+### 4. Email & Messages
+
+If you have access to communication context:
+- Summarize unread messages that need responses
+- Draft quick replies for straightforward ones — present them for review
+- Flag anything urgent or time-sensitive
+
+### 5. Tasks & Priorities
+
+If you have context on the user's work:
+- Surface top 3 priorities for the day
+- Note any deadlines approaching
+- Suggest one thing to tackle first
+
+### 6. Something Interesting
+
+End with one of:
+- An interesting fact or quote
+- A relevant article worth reading later
+- A tip related to something the user is working on
+
+## Tone
+
+- Concise and scannable — use bullet points, not paragraphs
+- Conversational but efficient — like a sharp executive assistant
+- Don't pad with filler — if you only have 2 useful sections, give 2 sections
+- Time-aware: morning briefings differ from afternoon check-ins
+
+## Adaptation Over Time
+
+As you learn more about the user:
+- Weight news toward their interests and industry
+- Remember their schedule patterns (e.g. "you usually have standup at 10")
+- Track recurring tasks and deadlines
+- Get more specific and less generic with each use

package/src/config/bundled-skills/start-the-day/icon.svg

@@ -0,0 +1,13 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect x="0" y="0" width="16" height="16" fill="#1a1a2e"/>
+  <rect x="2" y="2" width="12" height="12" fill="#16213e"/>
+  <rect x="3" y="3" width="10" height="10" fill="#0f3460"/>
+  <rect x="4" y="4" width="8" height="2" fill="#e94560"/>
+  <rect x="4" y="7" width="8" height="1" fill="#ffd700"/>
+  <rect x="4" y="9" width="8" height="1" fill="#ffd700"/>
+  <rect x="4" y="11" width="8" height="1" fill="#ffd700"/>
+  <rect x="2" y="2" width="1" height="12" fill="#16a085"/>
+  <rect x="13" y="2" width="1" height="12" fill="#16a085"/>
+  <rect x="7" y="1" width="2" height="1" fill="#ffd700"/>
+  <rect x="6" y="0" width="4" height="1" fill="#e94560"/>
+</svg>

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

@@ -0,0 +1,25 @@
+---
+name: "Subagent"
+description: "Spawn and manage autonomous background agents for parallel work"
+metadata: {"vellum": {"emoji": "\ud83e\udd16"}}
+---
+
+Subagent orchestration -- spawn background agents to work on tasks in parallel.
+
+## Lifecycle
+
+Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`
+
+- **Spawn**: Use `subagent_spawn` with a label and objective. The subagent runs autonomously.
+- **Auto-notification**: The parent session is automatically notified when a subagent reaches a terminal status. Do NOT poll `subagent_status`.
+- **Read output**: Use `subagent_read` only after the subagent reaches a terminal status (completed/failed/aborted).
+
+## Ownership
+
+Only the parent session that spawned a subagent can interact with it (check status, send messages, abort, or read output).
+
+## Tips
+
+- Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
+- Use `subagent_message` to send follow-up instructions to a running subagent.
+- Use `subagent_abort` to cancel a subagent that is no longer needed.

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

@@ -0,0 +1,107 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "subagent_spawn",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string",
+            "description": "Short human-readable label for this subagent (e.g. \"Research competitor pricing\")"
+          },
+          "objective": {
+            "type": "string",
+            "description": "The task objective — what the subagent should accomplish"
+          },
+          "context": {
+            "type": "string",
+            "description": "Optional additional context to pass to the subagent"
+          }
+        },
+        "required": ["label", "objective"]
+      },
+      "executor": "tools/subagent-spawn.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "subagent_status",
+      "description": "Get the status of a specific subagent or list all subagents for the current session. Only use this when the user explicitly asks about subagent status — do NOT poll automatically, as you will be notified when subagents complete.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "subagent_id": {
+            "type": "string",
+            "description": "Optional subagent ID to query. If omitted, returns all subagents for this session."
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/subagent-status.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "subagent_abort",
+      "description": "Abort a running subagent by ID.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "subagent_id": {
+            "type": "string",
+            "description": "The ID of the subagent to abort."
+          }
+        },
+        "required": ["subagent_id"]
+      },
+      "executor": "tools/subagent-abort.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "subagent_message",
+      "description": "Send a follow-up message to a running subagent.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "subagent_id": {
+            "type": "string",
+            "description": "The ID of the subagent to send a message to."
+          },
+          "content": {
+            "type": "string",
+            "description": "The message content to send to the subagent."
+          }
+        },
+        "required": ["subagent_id", "content"]
+      },
+      "executor": "tools/subagent-message.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "subagent_read",
+      "description": "Read the full conversation output from a subagent. Use this after a subagent completes to retrieve its full work product.",
+      "category": "orchestration",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "subagent_id": {
+            "type": "string",
+            "description": "The ID of the subagent whose output to read."
+          }
+        },
+        "required": ["subagent_id"]
+      },
+      "executor": "tools/subagent-read.ts",
+      "execution_target": "host"
+    }
+  ]
+}