vellum 0.2.1 → 0.2.2

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"
+    }
+  ]
+}

package/src/config/bundled-skills/subagent/tools/subagent-abort.ts

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

package/src/config/bundled-skills/subagent/tools/subagent-message.ts

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

package/src/config/bundled-skills/subagent/tools/subagent-read.ts

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

package/src/config/bundled-skills/subagent/tools/subagent-spawn.ts

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

package/src/config/bundled-skills/subagent/tools/subagent-status.ts

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

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

@@ -0,0 +1,28 @@
+---
+name: "Tasks"
+description: "Two-layer task system with reusable templates and a prioritized work queue"
+metadata: {"vellum": {"emoji": "\u2705"}}
+---
+
+Two-layer task system: **task templates** (reusable definitions with input placeholders) and **work items** (instances in the Task Queue with priority tiers and status tracking).
+
+## Task Templates
+
+Templates are reusable definitions saved from conversations via `task_save`. They capture the conversation pattern with placeholders that can be run later with different inputs via `task_run`. List templates with `task_list`, delete with `task_delete`.
+
+## Work Items (Task Queue)
+
+Work items are the user-facing "Tasks" shown in the Tasks panel. They track status and priority:
+
+- **Priority tiers**: 0 = high, 1 = medium (default), 2 = low
+- **Status flow**: queued -> running -> awaiting_review -> done
+- **Resolution precedence**: work_item_id > task_id > task_name > title
+
+Use `task_list_add` to enqueue items (ad-hoc or from a template), `task_list_show` to view the queue, `task_list_update` to modify, and `task_list_remove` to remove.
+
+## Tips
+
+- When the user says "add to my tasks" or "add to my queue", use `task_list_add` (NOT schedule_create or reminder_create).
+- Use `task_save` only when the user wants to capture a conversation pattern as a reusable template.
+- `task_list` shows saved templates; `task_list_show` shows the active work queue.
+- **Always specify `required_tools`** when calling `task_list_add`. Think about what tools the task will need at execution time and list them explicitly (e.g. `["host_bash"]` for shell commands, `["host_file_read", "host_file_write"]` for file operations, `["web_search", "web_fetch"]` for web lookups). The user must approve these tools before the task can run — omitting them forces a fallback to all tools, which is noisy and may miss non-standard tools the task actually needs.

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

@@ -0,0 +1,256 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "task_save",
+      "description": "Save the current conversation as a reusable task template (definition). This is NOT for adding items to the user's task queue — use task_list_add for that. task_save extracts the conversation pattern into a reusable definition with placeholders that can be run later with different inputs.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "conversation_id": {
+            "type": "string",
+            "description": "The conversation to capture as a task template. If omitted, uses the current conversation."
+          },
+          "title": {
+            "type": "string",
+            "description": "Optional override for the auto-generated task title"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/task-save.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_run",
+      "description": "Run a task template. Resolves the template by name (fuzzy match) or ID, renders it with the provided inputs, and returns the rendered prompt for execution as a Task (work item).",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "task_name": {
+            "type": "string",
+            "description": "Fuzzy match a task template by name (case-insensitive substring match)"
+          },
+          "task_id": {
+            "type": "string",
+            "description": "Exact match a task template by ID"
+          },
+          "inputs": {
+            "type": "object",
+            "description": "Values for template placeholders (e.g. {\"file_path\": \"/tmp/foo.txt\", \"url\": \"https://example.com\"})",
+            "additionalProperties": { "type": "string" }
+          }
+        }
+      },
+      "executor": "tools/task-run.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_list",
+      "description": "List saved task templates (reusable definitions). To see your active Tasks (work items), use task_list_show instead.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {}
+      },
+      "executor": "tools/task-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_delete",
+      "description": "Delete one or more task templates by ID. Also removes associated task runs and work items (Tasks).",
+      "category": "tasks",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "task_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "One or more task IDs to delete."
+          }
+        },
+        "required": ["task_ids"]
+      },
+      "executor": "tools/task-delete.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_list_show",
+      "description": "List the user's Task Queue (work items) with their status, priority, and last run info. Use this when the user says \"show my tasks\", \"what's in my queue\", \"what's on my task list\", or similar.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "array", "items": { "type": "string" } }
+            ],
+            "description": "Optional status filter. A single status string (e.g. \"queued\") or an array of statuses to include."
+          }
+        }
+      },
+      "executor": "tools/task-list-show.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_list_add",
+      "description": "Add a task to the user's Task Queue. Use this when the user says \"add to my tasks\", \"add to my queue\", \"put this on my task list\", \"track this task\", or any variation of adding a one-off item they want to remember or work on. You can provide just a title for ad-hoc items, or reference an existing task definition by name or ID. Do NOT use schedule_create or reminder for simple \"add to tasks\" requests — those are for timed/recurring automation only.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "description": "ID of an existing task definition to enqueue. Provide this, task_name, or just title."
+          },
+          "task_name": {
+            "type": "string",
+            "description": "Title/name of an existing task definition to search for (case-insensitive substring match). Provide this, task_id, or just title."
+          },
+          "title": {
+            "type": "string",
+            "description": "Title for the work item. When provided WITHOUT task_id or task_name, creates an ad-hoc work item directly (a lightweight task template is auto-created behind the scenes). When provided WITH task_id or task_name, overrides the task definition title."
+          },
+          "execution_prompt": {
+            "type": "string",
+            "description": "The full instruction to execute when this task runs. If omitted, the title is used as the execution prompt. Use this to preserve detailed instructions (e.g. full file paths, specific parameters) that would be lost in a short display title."
+          },
+          "notes": {
+            "type": "string",
+            "description": "Notes to attach to the work item."
+          },
+          "priority_tier": {
+            "type": "number",
+            "description": "0 = high, 1 = medium (default), 2 = low."
+          },
+          "sort_index": {
+            "type": "number",
+            "description": "Manual sort order within the priority tier."
+          },
+          "if_exists": {
+            "type": "string",
+            "enum": ["create_duplicate", "reuse_existing", "update_existing"],
+            "description": "What to do if an active work item with the same title already exists. Defaults to \"reuse_existing\"."
+          },
+          "required_tools": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Tools the task will need at execution time. Always specify this — think about what tools are needed to accomplish the task (e.g. [\"host_bash\"] for shell commands, [\"host_file_read\", \"host_file_write\"] for file operations, [\"web_search\"] for web lookups). The user must approve these before the task runs. Pass [] if no tools are needed."
+          }
+        }
+      },
+      "executor": "tools/task-list-add.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_list_update",
+      "description": "Update an existing task in the Task Queue. Can change priority, notes, status, or sort order. Identifies the task by work item ID, task ID, task name, or title.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Direct work item ID (most precise selector)"
+          },
+          "task_id": {
+            "type": "string",
+            "description": "Task definition ID to find the work item for"
+          },
+          "task_name": {
+            "type": "string",
+            "description": "Task name/title to search for (case-insensitive exact match)"
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title to search for (case-insensitive exact match)"
+          },
+          "priority_tier": {
+            "type": "number",
+            "description": "0 = high, 1 = medium, 2 = low"
+          },
+          "notes": {
+            "type": "string",
+            "description": "Updated notes for the work item"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["queued", "running", "awaiting_review", "failed", "cancelled", "archived"],
+            "description": "New status for the work item"
+          },
+          "sort_index": {
+            "type": "number",
+            "description": "Manual sort order within the same priority tier"
+          },
+          "filter_priority_tier": {
+            "type": "number",
+            "description": "Disambiguation filter: narrow by current priority tier (0=high, 1=medium, 2=low) when multiple items share the same title/task_id. This identifies WHICH item to update — it is NOT the new priority value."
+          },
+          "filter_status": {
+            "type": "string",
+            "enum": ["queued", "running", "awaiting_review", "failed", "cancelled", "done", "archived"],
+            "description": "Disambiguation filter: narrow by current status when multiple items share the same title/task_id."
+          },
+          "created_order": {
+            "type": "number",
+            "description": "Disambiguation filter: pick the Nth oldest match (1 = oldest, 2 = second oldest, etc.) when multiple items share the same title/task_id."
+          }
+        }
+      },
+      "executor": "tools/task-list-update.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "task_list_remove",
+      "description": "Remove a task from the Task Queue. Identifies the task by work item ID, task ID, task name, or title. When multiple items match, use the disambiguation fields (priority_tier, status, created_order) to narrow down.",
+      "category": "tasks",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Direct work item ID (most precise selector)"
+          },
+          "task_id": {
+            "type": "string",
+            "description": "Task definition ID to find the work item for"
+          },
+          "task_name": {
+            "type": "string",
+            "description": "Task name/title to search for (case-insensitive exact match)"
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title to search for (case-insensitive exact match)"
+          },
+          "priority_tier": {
+            "type": "number",
+            "description": "Disambiguator: filter by priority tier (0 = high, 1 = medium, 2 = low)"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["queued", "running", "awaiting_review", "failed", "cancelled"],
+            "description": "Disambiguator: filter by work item status"
+          },
+          "created_order": {
+            "type": "number",
+            "description": "Disambiguator: 1-indexed creation order among matches (1 = oldest, 2 = second oldest, etc.)"
+          }
+        }
+      },
+      "executor": "tools/task-list-remove.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/tasks/tools/task-delete.ts

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

package/src/config/bundled-skills/tasks/tools/task-list-add.ts

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

package/src/config/bundled-skills/tasks/tools/task-list-remove.ts

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

package/src/config/bundled-skills/tasks/tools/task-list-show.ts

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

package/src/config/bundled-skills/tasks/tools/task-list-update.ts

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

package/src/config/bundled-skills/tasks/tools/task-list.ts

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

package/src/config/bundled-skills/tasks/tools/task-run.ts

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

package/src/config/bundled-skills/tasks/tools/task-save.ts

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

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

@@ -0,0 +1,134 @@
+---
+name: "X"
+description: "Read and post on X (formerly Twitter) using your authenticated session"
+user-invocable: true
+metadata: {"vellum": {"emoji": "𝕏"}}
+---
+
+You are an X (formerly Twitter) assistant. Use the `execute_bash` tool to run `vellum x` CLI commands.
+
+## Posting
+
+```bash
+vellum x post "The post text here"
+```
+
+Returns JSON with `ok`, `tweetId`, `text`, and `url` fields. Share the URL with the user so they can verify the post.
+
+## Replying
+
+```bash
+vellum x reply <tweetUrl> "The reply text here"
+```
+
+The first argument is a tweet URL (e.g. `https://x.com/user/status/123456`) or a bare tweet ID.
+
+## Reading
+
+### User timeline
+```bash
+vellum x timeline <screenName> [--count N]
+```
+Returns `user` and `tweets` array.
+
+### Single tweet + replies
+```bash
+vellum x tweet <tweetIdOrUrl>
+```
+Returns the focal tweet and its reply thread.
+
+### Search
+```bash
+vellum x search "query" [--count N] [--product Top|Latest|People|Media]
+```
+
+### Home timeline
+```bash
+vellum x home [--count N]
+```
+
+### Bookmarks
+```bash
+vellum x bookmarks [--count N]
+```
+
+### Notifications
+```bash
+vellum x notifications [--count N]
+```
+Returns `notifications` array with `id`, `message`, `timestamp`, `url`.
+
+### Likes
+```bash
+vellum x likes <screenName> [--count N]
+```
+
+### Followers / Following
+```bash
+vellum x followers <screenName> [--count N]
+vellum x following <screenName> [--count N]
+```
+Returns `user` and `followers`/`following` array (userId, screenName, name).
+
+### Media
+```bash
+vellum x media <screenName> [--count N]
+```
+Returns tweets that contain media from the user's profile.
+
+## Session Management
+
+Check if a session exists:
+```bash
+vellum x status --json
+```
+
+If there is no session or the session has expired, refresh it:
+```bash
+vellum x refresh
+```
+
+This opens Chrome, navigates through x.com automatically, and captures auth cookies. Do NOT tell the user to run this manually — run it yourself.
+
+## Workflows
+
+### Check Mentions
+
+When the user asks to check mentions, check X, or see what's happening:
+
+1. Fetch notifications: `vellum x notifications --count 20 --json`
+2. Fetch their recent tweets to see replies: `vellum x timeline <theirScreenName> --count 10 --json`
+3. Summarize what needs attention:
+   - Group by type: replies to their tweets, likes, new followers, mentions
+   - For anything that looks like it needs a reply, fetch the full thread with `vellum x tweet <tweetId>` to understand context
+   - Prioritize: direct questions > mentions > engagement notifications
+4. For items that need replies, draft a response and ask the user to approve before sending with `vellum x reply`
+
+Present the summary as a scannable list, not a wall of text. Lead with action items.
+
+### Research a Topic
+
+When the user wants to understand what people are saying about something:
+
+1. Search: `vellum x search "topic" --count 20 --json`
+2. For the most interesting tweets, fetch threads: `vellum x tweet <tweetId>`
+3. Summarize: key themes, notable voices, sentiment, and any emerging consensus
+4. If the user wants to engage, draft a post or reply that adds to the conversation
+
+### Engagement Check
+
+When the user wants to see how their posts are performing:
+
+1. Fetch their recent tweets: `vellum x timeline <screenName> --count 20 --json`
+2. For each tweet, note engagement signals from the text/metadata
+3. Fetch notifications to see who's interacting: `vellum x notifications --count 20 --json`
+4. Summarize: which posts got traction, who's engaging, any conversations worth continuing
+
+## Tips
+
+- Keep posts under 280 characters
+- All `screenName` arguments should be without the `@` prefix
+- All commands return JSON with an `ok` field
+- When drafting replies, match the tone of the conversation — casual threads get casual replies
+- Always show the user what you're about to post and get approval before sending
+- If a session is expired, refresh it silently with `vellum x refresh` before retrying