@vellumai/assistant 0.3.0

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -0,0 +1,57 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { mergeContacts, getContact } from '../../../../contacts/contact-store.js';
+
+export async function executeContactMerge(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const keepId = input.keep_id as string | undefined;
+  const mergeId = input.merge_id as string | undefined;
+
+  if (!keepId || typeof keepId !== 'string') {
+    return { content: 'Error: keep_id is required', isError: true };
+  }
+  if (!mergeId || typeof mergeId !== 'string') {
+    return { content: 'Error: merge_id is required', isError: true };
+  }
+
+  // Show what will be merged for clarity
+  const keepContact = getContact(keepId);
+  const mergeContact = getContact(mergeId);
+
+  if (!keepContact) {
+    return { content: `Error: Contact "${keepId}" not found`, isError: true };
+  }
+  if (!mergeContact) {
+    return { content: `Error: Contact "${mergeId}" not found`, isError: true };
+  }
+
+  try {
+    const merged = mergeContacts(keepId, mergeId);
+
+    const channelList = merged.channels
+      .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
+      .join('\n');
+
+    return {
+      content: [
+        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
+        ``,
+        `Surviving contact (${merged.id}):`,
+        `  Name: ${merged.displayName}`,
+        `  Importance: ${merged.importance.toFixed(2)}`,
+        `  Interactions: ${merged.interactionCount}`,
+        merged.relationship ? `  Relationship: ${merged.relationship}` : null,
+        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+        ``,
+        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
+      ].filter(Boolean).join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}
+
+export { executeContactMerge as run };

package/src/config/bundled-skills/contacts/tools/contact-search.ts

@@ -0,0 +1,60 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { searchContacts } from '../../../../contacts/contact-store.js';
+import type { ContactWithChannels } from '../../../../contacts/types.js';
+
+function formatContactSummary(c: ContactWithChannels): string {
+  const parts = [`- **${c.displayName}** (ID: ${c.id})`];
+  if (c.relationship) parts.push(`  Relationship: ${c.relationship}`);
+  parts.push(`  Importance: ${c.importance.toFixed(2)} | Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    const channelList = c.channels
+      .map((ch) => `${ch.type}:${ch.address}${ch.isPrimary ? '*' : ''}`)
+      .join(', ');
+    parts.push(`  Channels: ${channelList}`);
+  }
+  return parts.join('\n');
+}
+
+export async function executeContactSearch(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const query = input.query as string | undefined;
+  const channelAddress = input.channel_address as string | undefined;
+  const channelType = input.channel_type as string | undefined;
+  const relationship = input.relationship as string | undefined;
+  const limit = input.limit as number | undefined;
+
+  if (!query && !channelAddress && !relationship) {
+    return {
+      content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
+      isError: true,
+    };
+  }
+
+  try {
+    const results = searchContacts({
+      query,
+      channelAddress,
+      channelType,
+      relationship,
+      limit,
+    });
+
+    if (results.length === 0) {
+      return { content: 'No contacts found matching the search criteria.', isError: false };
+    }
+
+    const lines = [`Found ${results.length} contact(s):\n`];
+    for (const contact of results) {
+      lines.push(formatContactSummary(contact));
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}
+
+export { executeContactSearch as run };

package/src/config/bundled-skills/contacts/tools/contact-upsert.ts

@@ -0,0 +1,66 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { upsertContact } from '../../../../contacts/contact-store.js';
+
+function formatContact(c: ReturnType<typeof upsertContact>): string {
+  const lines = [
+    `Contact ${c.id}`,
+    `  Name: ${c.displayName}`,
+  ];
+  if (c.relationship) lines.push(`  Relationship: ${c.relationship}`);
+  lines.push(`  Importance: ${c.importance.toFixed(2)}`);
+  if (c.responseExpectation) lines.push(`  Response expectation: ${c.responseExpectation}`);
+  if (c.preferredTone) lines.push(`  Preferred tone: ${c.preferredTone}`);
+  if (c.interactionCount > 0) lines.push(`  Interactions: ${c.interactionCount}`);
+  if (c.channels.length > 0) {
+    lines.push('  Channels:');
+    for (const ch of c.channels) {
+      const primary = ch.isPrimary ? ' (primary)' : '';
+      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export async function executeContactUpsert(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const displayName = input.display_name as string | undefined;
+  if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
+    return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
+  }
+
+  const importance = input.importance as number | undefined;
+  if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
+    return { content: 'Error: importance must be a number between 0 and 1', isError: true };
+  }
+
+  const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
+  const channels = rawChannels?.map((ch) => ({
+    type: ch.type,
+    address: ch.address,
+    isPrimary: ch.is_primary,
+  }));
+
+  try {
+    const contact = upsertContact({
+      id: input.id as string | undefined,
+      displayName: displayName.trim(),
+      relationship: input.relationship as string | undefined,
+      importance,
+      responseExpectation: input.response_expectation as string | undefined,
+      preferredTone: input.preferred_tone as string | undefined,
+      channels,
+    });
+
+    return {
+      content: `${contact.created ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}
+
+export { executeContactUpsert as run };

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

@@ -0,0 +1,26 @@
+---
+name: "Document"
+description: "Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides). Use when the user says write, draft, compose, or create a blog/article/essay."
+metadata: {"vellum": {"emoji": "📄"}}
+---
+
+Create and edit long-form documents using the built-in rich text editor. Documents open in workspace mode with chat docked to the side.
+
+## Tools
+
+- **document_create** — Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
+- **document_update** — Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
+
+## Workflow
+
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, *italic*, code blocks, tables, lists, blockquotes as appropriate.
+3. **CRITICAL — Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
+4. **Respond to edits**: When the user requests changes via the docked chat, use `document_update` with `replace` for full rewrites or `append` for additions.
+
+## Usage Notes
+
+- The `mode` parameter on `document_update` defaults to `append`.
+- Documents are automatically saved and accessible via the Generated panel.
+- Users can manually edit documents at any time.
+- Write in clear, engaging prose. Use active voice, vary sentence structure, and break content into logical sections with descriptive headings.

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

@@ -0,0 +1,53 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "document_create",
+      "description": "Create a new long-form document with a rich text editor. Use this when the user asks to write a blog post, article, or any long-form content. The editor opens in workspace mode with chat docked to the side.",
+      "category": "document",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Initial title for the document (optional, can be updated later)"
+          },
+          "initial_content": {
+            "type": "string",
+            "description": "Initial Markdown content to populate the editor (optional)"
+          }
+        }
+      },
+      "executor": "tools/document-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_update",
+      "description": "Update content in an open document editor. Use this to stream generated content or apply edits.",
+      "category": "document",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document surface to update"
+          },
+          "content": {
+            "type": "string",
+            "description": "Markdown content to set or append"
+          },
+          "mode": {
+            "type": "string",
+            "enum": ["replace", "append"],
+            "description": "Whether to replace all content or append to the end. Defaults to append."
+          }
+        },
+        "required": ["surface_id", "content"]
+      },
+      "executor": "tools/document-update.ts",
+      "execution_target": "host"
+    }
+  ]
+}

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

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

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

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

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

@@ -0,0 +1,163 @@
+---
+name: "DoorDash"
+description: "Order food, groceries, and convenience items from DoorDash using the built-in CLI integration"
+user-invocable: true
+metadata: {"vellum": {"emoji": "\uD83C\uDF55"}}
+---
+
+You can order food from DoorDash for the user using the `vellum doordash` CLI.
+
+## CLI Setup
+
+**IMPORTANT: Always use `host_bash` (not `bash`) for all `vellum doordash` commands.** The DoorDash CLI needs host access for Chrome CDP, session cookies, and the `vellum` binary — none of which are available inside the sandbox.
+
+`vellum doordash` is a built-in subcommand of the Vellum assistant CLI — it is NOT a separate tool you need to find or install. It should already be on your PATH. If `vellum` is not found, prepend `PATH="$HOME/.local/bin:$PATH"` to the command. Do NOT search for the binary, inspect wrapper scripts, or try to discover how the CLI works. Just run the commands as documented below.
+
+## Task Progress Widget
+
+A task progress card is shown automatically when you run your first `vellum doordash` command. Its surface ID is `doordash-progress`. As each step completes, call `ui_update` with surface ID `doordash-progress` to update step statuses. Update `data.templateData.steps` — set completed steps to `"status": "completed"` with a `"detail"` string, the current step to `"status": "in_progress"`, and future steps to `"status": "pending"`. Adapt the steps to the actual flow (e.g. skip "Search restaurants" if the user named a specific store).
+
+## Typical Flow
+
+When the user asks you to order food (e.g. "Order pizza from Andiamo's"):
+
+1. **Check session** — run `vellum doordash status --json`. If `loggedIn` is false or the session is expired, tell the user: "A Chrome window will open to the DoorDash login page. Please sign in there — I'll detect your login automatically and minimize the window." Then run `vellum doordash refresh --json`. This starts a Ride Shotgun learn session that records your login and auto-stops once it detects you've signed in. The session is imported automatically. **This command blocks until login is complete — just wait for it.**
+
+   Keep the DoorDash Chrome window open in the background — it's needed for API requests.
+
+2. **Search** — run `vellum doordash search "<query>" --json` to find matching restaurants. Present the top results to the user with name, rating, and delivery info. If the user named a specific restaurant, pick the best match. If ambiguous, ask.
+
+3. **Browse menu** — run `vellum doordash menu <storeId> --json` to get the menu. Show the user the categories and items with prices. If the user already said what they want (e.g. "pepperoni pizza"), find the matching item(s). **For convenience/pharmacy stores** (CVS, Duane Reade, Walgreens etc.), the response will have `isRetail: true` and empty items — use `store-search` instead (see step 3b).
+
+3b. **Search within a retail store** — for convenience/pharmacy stores, run `vellum doordash store-search <storeId> "<query>" --json` to find specific products. This returns items with IDs, prices, and menuIds that can be added to cart directly.
+
+4. **Get item details** (if needed) — run `vellum doordash item <storeId> <itemId> --json` to see options/customizations. The response includes:
+   - `options`: each option group has `minSelections`/`maxSelections` indicating how many choices are required
+   - Each choice has `unitAmount` (price impact in cents), `defaultQuantity`, and possibly `nestedOptions` (sub-choices like milk type within a size selection)
+   - `specialInstructionsConfig`: whether special instructions are accepted, max length, and placeholder text
+
+   If the item has required options (like size or toppings), construct the `nestedOptions` JSON from the option/choice IDs and pass it via `--options`. Ask the user for preferences or pick sensible defaults.
+
+5. **Add to cart** — run `vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--options '<json>'] [--special-instructions "<text>"] --json`. For subsequent items at the same store, pass `--cart-id <id>` from the first add response. Use `--special-instructions` for requests like "extra hot", "no ice", etc. Use `--options` to pass customization choices (see Customization Options below).
+
+6. **Review cart** — run `vellum doordash cart view <cartId> --json` and show the user what's in their cart with prices. Ask if they want to add anything else or proceed.
+
+7. **Checkout** — run `vellum doordash checkout <cartId> --json` to get delivery options. Present them to the user.
+
+8. **Payment methods** — run `vellum doordash payment-methods --json` to see saved cards. Show the user which card will be used (the default one).
+
+9. **Place order** — after the user explicitly confirms, run `vellum doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--dropoff-option <id>] --json`. The command auto-selects the default payment method if `--payment-uuid` is not provided. The response contains `orderUuid` on success.
+
+## Important Behavior
+
+- **Always confirm before checkout.** Never place an order without explicit user approval.
+- **Be proactive.** If the user says "order pizza from Andiamo's", don't ask clarifying questions upfront — search, find the store, show the menu, and suggest items. Only ask when you need a choice the user hasn't specified.
+- **Handle expired sessions gracefully.** If any command returns `"error": "session_expired"`, run `vellum doordash refresh --json` to re-capture the session.
+- **Show prices.** Always show prices when presenting items or the cart summary.
+- **Use `--json` flag** on all commands for reliable parsing.
+- **Do NOT use the browser skill.** All DoorDash interaction goes through the CLI, not browser automation.
+- **Rate limiting.** DoorDash rate-limits rapid sequential requests. When adding multiple items (e.g. a team order), wait 8–10 seconds between `cart add` calls. If you get a 403 error, wait 15–20 seconds and retry. For large orders (5+ items), consider running `vellum doordash refresh --json` midway through if you hit repeated 403s.
+- **Special instructions are unreliable.** Some merchants disable special instructions entirely. Always prefer `--options` for customizations (size, milk type, etc.). Only use `--special-instructions` for free-text requests that aren't covered by the item's option groups. If the merchant rejects special instructions, drop them and proceed without.
+- **Customization fallback.** If `cart add` with `--options` fails, or if the item details show options that are hard to construct (deeply nested, unusual format), proactively offer to use `cart learn` so the user can customize the item visually in the browser. Don't silently drop customizations — tell the user what happened and offer alternatives.
+- **Always-allow tip.** At the start of an ordering flow, suggest the user enable "always allow" for `vellum doordash` commands: "Tip: You can type 'a' to always allow `vellum doordash` commands for this session so you won't be prompted each time."
+- **Error attribution.** When errors occur, assume it's more likely a bug in our query/parsing than a DoorDash API change. Suggest running `vellum doordash record` to capture fresh queries before assuming the schema changed.
+
+## Customization Options
+
+Many items (especially coffee, boba, sandwiches) have required customization options like size, milk type, or toppings. Here's how to handle them:
+
+### Constructing nestedOptions JSON
+
+1. Run `vellum doordash item <storeId> <itemId> --json` to get the item's option groups
+2. Each option group has `id`, `name`, `required`, `minSelections`, `maxSelections`, and `choices`
+3. Build a JSON array of selections matching the DoorDash format:
+
+```json
+[
+  {
+    "optionId": "<option-group-id>",
+    "optionChoiceId": "<choice-id>",
+    "quantity": 1,
+    "nestedOptions": []
+  }
+]
+```
+
+For choices with nested sub-options (e.g., selecting "Oat Milk" under the "Milk" option within a size), add them to the `nestedOptions` array of the parent choice.
+
+4. Pass the JSON string to `cart add --options '<json>'`
+
+### Special Instructions
+
+Use `--special-instructions` on `cart add` for free-text requests like "extra hot", "no ice", "light foam". The `item` command response includes `specialInstructionsConfig` with the max length and whether instructions are supported.
+
+**Warning:** Some merchants disable special instructions entirely. If `specialInstructionsConfig.isEnabled` is false, or if the add-to-cart call returns an error about special requests, drop the instructions and retry without them. Always prefer `--options` for customizations — special instructions are a last resort for requests not covered by the item's option groups.
+
+### Learning Customizations via Ride Shotgun
+
+For complex items where constructing the JSON manually is difficult, use `cart learn`:
+
+1. Run `vellum doordash cart learn --json`
+2. A Chrome window opens — navigate to the item, customize it visually, and click "Add to Cart"
+3. The command auto-detects the `updateCartItem` operation and extracts the exact `nestedOptions` and `specialInstructions`
+4. Use the extracted options directly with `cart add --options '<json>'`
+
+You can also extract options from an existing recording with `vellum doordash inspect <recordingId> --extract-options --json`.
+
+### Coffee Order Example
+
+**User**: "Order a large oat milk latte with an extra shot from Blue Bottle"
+
+1. `vellum doordash search "Blue Bottle" --json` -> finds store
+2. `vellum doordash menu <storeId> --json` -> finds "Latte" item
+3. `vellum doordash item <storeId> <latteItemId> --json` -> returns options:
+   - Size (required, min:1, max:1): Small (id:101), Medium (id:102), Large (id:103, +$1.00)
+   - Milk (required, min:1, max:1): Whole (id:201), Oat (id:202, +$0.70), Almond (id:203, +$0.70)
+   - Extras (optional, min:0, max:5): Extra Shot (id:301, +$0.90), Vanilla Syrup (id:302, +$0.60)
+4. Construct options JSON and add to cart:
+```
+vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "Latte" --unit-price 550 --options '[{"optionId":"size-group-id","optionChoiceId":"103","quantity":1,"nestedOptions":[]},{"optionId":"milk-group-id","optionChoiceId":"202","quantity":1,"nestedOptions":[]},{"optionId":"extras-group-id","optionChoiceId":"301","quantity":1,"nestedOptions":[]}]' --special-instructions "Extra hot" --json
+```
+
+## Command Reference
+
+```
+vellum doordash status --json              # Check if logged in
+vellum doordash refresh --json             # Capture fresh session via Ride Shotgun (auto-stops after login)
+vellum doordash login --recording <path>   # Import session from a recording file manually
+vellum doordash logout --json              # Clear session
+vellum doordash search "<query>" --json    # Search restaurants
+vellum doordash menu <storeId> --json      # Get store menu (auto-detects retail stores)
+vellum doordash store-search <storeId> "<query>" --json  # Search items within a convenience/pharmacy store
+vellum doordash item <storeId> <itemId> --json  # Get item details + options
+vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--quantity <n>] [--cart-id <id>] [--options '<json>'] [--special-instructions "<text>"] --json
+vellum doordash cart remove --cart-id <id> --item-id <orderItemId> --json
+vellum doordash cart view <cartId> --json
+vellum doordash cart list [--store-id <id>] --json
+vellum doordash cart learn --json                 # Learn customization options by recording browser interaction
+vellum doordash inspect <recordingId> --extract-options --json  # Extract nestedOptions from a recording
+vellum doordash checkout <cartId> [--address-id <id>] --json
+vellum doordash payment-methods --json     # List saved payment methods
+vellum doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--delivery-option <type>] [--dropoff-option <id>] [--payment-uuid <uuid>] --json
+```
+
+## Example Interaction
+
+**User**: "Order a pepperoni pizza from Andiamo's"
+
+1. `vellum doordash status --json` -> logged in
+2. `vellum doordash search "Andiamo's" --json` -> finds store 22926474
+3. `vellum doordash menu 22926474 --json` -> finds "Pepperoni Pizza Pie" (item 2956709006, $28.00)
+4. Tell user: "I found Pepperoni Pizza Pie at Andiamo's for $28.00. Adding it to your cart."
+5. `vellum doordash cart add --store-id 22926474 --menu-id 12847574 --item-id 2956709006 --item-name "Pepperoni Pizza Pie" --unit-price 2800 --json`
+6. `vellum doordash cart view <cartId> --json` -> show summary
+7. "Your cart has 1x Pepperoni Pizza Pie ($28.00), total $28.00. Ready to check out?"
+
+**User**: "I need Tylenol from CVS"
+
+1. `vellum doordash status --json` -> logged in
+2. `vellum doordash search "CVS" --json` -> finds store 1231787
+3. `vellum doordash menu 1231787 --json` -> isRetail: true, categories but no items
+4. `vellum doordash store-search 1231787 "tylenol" --json` -> finds results
+5. Show top results: "Tylenol Extra Strength Gelcaps (24 ct) - $8.79, Tylenol Extra Strength Caplets (100 ct) - $13.49..."
+6. User picks one -> add to cart with the item's `id`, `menuId`, and `unitAmount`

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

@@ -0,0 +1,32 @@
+---
+name: "Followups"
+description: "Track sent messages awaiting responses across communication channels"
+metadata: {"vellum": {"emoji": "\ud83d\udce8"}}
+---
+
+Track messages sent on external channels (email, Slack, WhatsApp, etc.) that are awaiting a response.
+
+## Lifecycle
+
+Each follow-up moves through these states:
+
+- **pending** -- waiting for a response
+- **overdue** -- past the expected response deadline with no reply
+- **nudged** -- a reminder was sent after becoming overdue
+- **resolved** -- a response was received or the follow-up was manually closed
+
+## Auto-Deadline
+
+When `expected_response_hours` is set, the follow-up automatically becomes overdue after that window. If a `contact_id` is provided, the contact's importance score can inform grace period decisions.
+
+## Resolution
+
+Follow-ups can be resolved in two ways:
+1. **By ID** -- resolve a specific follow-up directly
+2. **By thread** -- provide channel + thread_id to auto-resolve all matching pending follow-ups (useful when a response arrives on a thread)
+
+## Tips
+
+- Use `followup_list` with `overdue_only: true` to find conversations that need attention.
+- Attach a `reminder_schedule_id` to link a recurring reminder schedule to a follow-up.
+- Filter by channel, status, or contact to narrow results.

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

@@ -0,0 +1,100 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "followup_create",
+      "description": "Create a follow-up tracker for a sent message. Tracks conversations awaiting a response across channels (email, Slack, WhatsApp, etc.).",
+      "category": "followups",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "description": "Communication channel (e.g. email, slack, whatsapp)"
+          },
+          "thread_id": {
+            "type": "string",
+            "description": "External thread or conversation identifier on that channel"
+          },
+          "contact_id": {
+            "type": "string",
+            "description": "Optional contact ID from the contact graph. Used for grace period context."
+          },
+          "expected_response_hours": {
+            "type": "number",
+            "description": "Hours to wait for a response before marking as overdue. If omitted, no deadline is set."
+          },
+          "reminder_schedule_id": {
+            "type": "string",
+            "description": "Optional recurrence schedule ID to fire a reminder when overdue"
+          },
+          "reminder_cron_id": {
+            "type": "string",
+            "description": "Deprecated alias for reminder_schedule_id. Use reminder_schedule_id instead."
+          }
+        },
+        "required": ["channel", "thread_id"]
+      },
+      "executor": "tools/followup-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "followup_list",
+      "description": "List follow-ups with optional filters by status, channel, or contact. Can also show only overdue follow-ups.",
+      "category": "followups",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["pending", "resolved", "overdue", "nudged"],
+            "description": "Filter by status (pending, resolved, overdue, nudged)"
+          },
+          "channel": {
+            "type": "string",
+            "description": "Filter by communication channel (e.g. email, slack)"
+          },
+          "contact_id": {
+            "type": "string",
+            "description": "Filter by contact ID"
+          },
+          "overdue_only": {
+            "type": "boolean",
+            "description": "When true, return only pending follow-ups past their expected response deadline"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/followup-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "followup_resolve",
+      "description": "Manually resolve a follow-up by ID, or auto-resolve by channel + thread ID when a response is received.",
+      "category": "followups",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Follow-up ID to resolve directly"
+          },
+          "channel": {
+            "type": "string",
+            "description": "Channel to match (used with thread_id for auto-resolution)"
+          },
+          "thread_id": {
+            "type": "string",
+            "description": "Thread ID to match (used with channel for auto-resolution)"
+          }
+        },
+        "required": []
+      },
+      "executor": "tools/followup-resolve.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/followups/icon.svg

@@ -0,0 +1,24 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" fill="#f5f5f5"/>
+  
+  <!-- Envelope body -->
+  <rect x="2" y="4" width="12" height="8" fill="#4a90e2" stroke="#2c5aa0" stroke-width="1"/>
+  
+  <!-- Envelope flap -->
+  <polygon points="2,4 8,8 14,4" fill="#357abd"/>
+  
+  <!-- Paper/message inside -->
+  <rect x="3" y="6" width="10" height="5" fill="#ffffff"/>
+  
+  <!-- Lines on paper -->
+  <line x1="4" y1="7" x2="12" y2="7" stroke="#d0d0d0" stroke-width="1"/>
+  <line x1="4" y1="8.5" x2="12" y2="8.5" stroke="#d0d0d0" stroke-width="1"/>
+  <line x1="4" y1="10" x2="10" y2="10" stroke="#d0d0d0" stroke-width="1"/>
+  
+  <!-- Clock overlay (top right) -->
+  <circle cx="11" cy="3" r="2.5" fill="#ff6b6b" stroke="#c92a2a" stroke-width="0.5"/>
+  
+  <!-- Clock hands -->
+  <line x1="11" y1="1.5" x2="11" y2="2.2" stroke="#ffffff" stroke-width="0.8" stroke-linecap="round"/>
+  <line x1="12.2" y1="3" x2="11.7" y2="3" stroke="#ffffff" stroke-width="0.8" stroke-linecap="round"/>
+</svg>

package/src/config/bundled-skills/followups/tools/followup-create.ts

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

package/src/config/bundled-skills/followups/tools/followup-list.ts

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

package/src/config/bundled-skills/followups/tools/followup-resolve.ts

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