vellum 0.2.1 → 0.2.2

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

@@ -0,0 +1,126 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "playbook_create",
+      "description": "Create an action playbook \u2014 a trigger\u2192action rule that tells the assistant how to handle incoming messages matching a pattern",
+      "category": "playbook",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "trigger": {
+            "type": "string",
+            "description": "Pattern or description that triggers this playbook (e.g. \"meeting request\", \"from:ceo@*\", \"newsletter\")"
+          },
+          "action": {
+            "type": "string",
+            "description": "What to do when the trigger matches \u2014 natural language action description (e.g. \"check calendar, propose 3 times\")"
+          },
+          "channel": {
+            "type": "string",
+            "description": "Channel this rule applies to (e.g. \"email\", \"slack\"), or \"*\" for all channels. Defaults to \"*\"."
+          },
+          "category": {
+            "type": "string",
+            "description": "Free-form category for grouping (e.g. \"scheduling\", \"triage\"). Defaults to \"general\"."
+          },
+          "autonomy_level": {
+            "type": "string",
+            "enum": ["auto", "draft", "notify"],
+            "description": "How much autonomy: \"auto\" = execute automatically, \"draft\" = draft for review, \"notify\" = notify only. Defaults to \"draft\"."
+          },
+          "priority": {
+            "type": "number",
+            "description": "Relative priority \u2014 higher numbers take precedence. Defaults to 0."
+          }
+        },
+        "required": ["trigger", "action"]
+      },
+      "executor": "tools/playbook-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "playbook_list",
+      "description": "List action playbooks, optionally filtered by channel or category",
+      "category": "playbook",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "description": "Filter by channel (e.g. \"email\", \"slack\"). Omit to show all."
+          },
+          "category": {
+            "type": "string",
+            "description": "Filter by category (e.g. \"scheduling\", \"triage\"). Omit to show all."
+          }
+        }
+      },
+      "executor": "tools/playbook-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "playbook_update",
+      "description": "Update an existing action playbook rule",
+      "category": "playbook",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "playbook_id": {
+            "type": "string",
+            "description": "ID of the playbook to update (from playbook_list results)"
+          },
+          "trigger": {
+            "type": "string",
+            "description": "Updated trigger pattern"
+          },
+          "action": {
+            "type": "string",
+            "description": "Updated action description"
+          },
+          "channel": {
+            "type": "string",
+            "description": "Updated channel (\"*\" for all)"
+          },
+          "category": {
+            "type": "string",
+            "description": "Updated category"
+          },
+          "autonomy_level": {
+            "type": "string",
+            "enum": ["auto", "draft", "notify"],
+            "description": "Updated autonomy level"
+          },
+          "priority": {
+            "type": "number",
+            "description": "Updated priority"
+          }
+        },
+        "required": ["playbook_id"]
+      },
+      "executor": "tools/playbook-update.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "playbook_delete",
+      "description": "Delete an action playbook rule",
+      "category": "playbook",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "playbook_id": {
+            "type": "string",
+            "description": "ID of the playbook to delete (from playbook_list results)"
+          }
+        },
+        "required": ["playbook_id"]
+      },
+      "executor": "tools/playbook-delete.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/playbooks/tools/playbook-create.ts

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

package/src/config/bundled-skills/playbooks/tools/playbook-delete.ts

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

package/src/config/bundled-skills/playbooks/tools/playbook-list.ts

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

package/src/config/bundled-skills/playbooks/tools/playbook-update.ts

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

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/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.