@vellumai/assistant 0.4.44 → 0.4.45

package/src/config/bundled-skills/telegram-setup/SKILL.md

@@ -1,105 +0,0 @@
----
-name: telegram-setup
-description: Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"🤖","vellum":{"display-name":"Telegram Setup","user-invocable":true,"includes":["public-ingress"]}}
----
-
-You are helping your user connect a Telegram bot to the Vellum Assistant gateway. Walk through each step below.
-
-## Value Classification
-
-| Value          | Type       | Storage method                              | Secret? |
-| -------------- | ---------- | ------------------------------------------- | ------- |
-| Bot Token      | Credential | `credential_store` prompt                   | **Yes** |
-| Bot Username   | Config     | `assistant config set telegram.botUsername` | No      |
-| Webhook Secret | Credential | `assistant credentials set`                 | **Yes** |
-
-- **Bot Token** is a secret. Always collect via `credential_store` prompt — never accept it pasted in plaintext chat.
-- **Bot Username** is derived from the token via the Telegram API and stored as config.
-
-# Setup Steps
-
-## Step 1: Collect Bot Token Securely
-
-Tell the user: **"You'll need a Telegram bot token from @BotFather. Open Telegram, message @BotFather, and use /newbot to create one."**
-
-Collect the token through the secure credential prompt:
-
-- Call `credential_store` with `action: "prompt"`, `service: "telegram"`, `field: "bot_token"`, `label: "Telegram Bot Token"`, `description: "Enter the bot token you received from @BotFather"`, `placeholder: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`.
-
-## Step 2: Validate Token and Configure Bot
-
-```bash
-BOT_TOKEN=$(assistant credentials reveal telegram:bot_token)
-GETME_RESPONSE=$(curl -sf "https://api.telegram.org/bot${BOT_TOKEN}/getMe")
-BOT_USERNAME=$(echo "$GETME_RESPONSE" | jq -r '.result.username')
-assistant config set telegram.botUsername "$BOT_USERNAME"
-```
-
-If the `curl` call fails, the token is invalid — ask the user to re-enter (repeat Step 1).
-
-
-## Step 3: Set Up Public Ingress and Webhooks
-
-### Verify Public Ingress is Set Up
-
-Telegram needs a publicly reachable URL to send webhook events to. Load the `public-ingress` skill to determine whether a public ingress has been configured and walk the user through setting one up if not.
-
-### Generate Webhook Secret
-
-Check to see if one already exists:
-```bash
-assistant credentials inspect telegram:webhook_secret
-```
-
-If not, generate and set one:
-
-```bash
-assistant credentials set telegram:webhook_secret "$(uuidgen)"
-```
-
-### Register Platform Callback Route
-
-```bash
-assistant platform callback-routes register --path webhooks/telegram --type telegram --json
-```
-
-Only needed for containerized deployments. A "not available" error is expected locally — ignore it.
-
-## Step 4: Register Bot Commands
-
-```bash
-BOT_TOKEN=$(assistant credentials reveal telegram:bot_token)
-curl -sf -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setMyCommands" \
-  -H "Content-Type: application/json" \
-  -d '{"commands":[{"command":"new","description":"Start a new conversation"},{"command":"help","description":"Show available commands"}]}'
-```
-
-Non-critical — warn on failure but don't block setup.
-
-## Step 5: Guardian Verification (Optional)
-
-Link the user's Telegram account as a trusted guardian. Load the **guardian-verify-setup** skill:
-
-- Call `skill_load` with `skill: "guardian-verify-setup"`.
-
-If the user declines, skip and continue.
-
-## Step 7: Report Success
-
-Summarize:
-
-- Bot verified and credentials stored
-- Bot commands registered: /new, /help
-- Guardian identity: {verified | skipped}
-
-# Clearing Credentials
-
-To disconnect Telegram:
-
-```bash
-assistant credentials delete telegram:bot_token
-assistant credentials delete telegram:webhook_secret
-assistant config set telegram.botUsername ""
-```

package/src/config/bundled-skills/time-based-actions/SKILL.md

@@ -1,142 +0,0 @@
----
-name: time-based-actions
-description: Unified routing guide for reminders, schedules, notifications, and tasks — prevents common misrouting
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"⏰","vellum":{"display-name":"Time-Based Actions"}}
----
-
-Quick-reference decision guide for choosing the right tool when users ask about time-triggered actions, recurring automation, notifications, or task tracking.
-
-## Decision Tree
-
-1. **Does the request have a specific future time AND should fire only once?**
-   - YES -> `reminder_create`
-   - Examples: "remind me at 3pm", "remind me in 5 minutes", "alert me tomorrow at 9am"
-
-2. **Does the request have a recurring pattern?**
-   - YES -> `schedule_create`
-   - Examples: "every day at 9am", "weekly on Mondays", "every 2 hours"
-
-3. **Does the request need an alert RIGHT NOW (no delay)?**
-   - YES -> `send_notification`
-   - Examples: "send me a notification", "alert me now", "ping me"
-
-4. **Is the request about tracking work with no time trigger?**
-   - YES -> `task_list_add`
-   - Examples: "add to my tasks", "remind me to do X" (no time), "put this on my list"
-
-## Critical Warning: `send_notification` is IMMEDIATE-ONLY
-
-`send_notification` fires **instantly** when called. It has **NO delay, scheduling, or future-time capability**. NEVER use it for:
-- "Remind me in 5 minutes" -> use `reminder_create`
-- "Alert me at 3pm" -> use `reminder_create`
-- "Notify me tomorrow" -> use `reminder_create`
-
-If you use `send_notification` for any of these, the notification fires immediately and the user misses their intended reminder.
-
-## Critical Warning: `task_list_add` has NO time trigger
-
-`task_list_add` creates a work queue item. It does **NOT** fire at a specific time. NEVER use it as a workaround for delayed notifications. If the user wants a timed alert, use `reminder_create`.
-
-## Time Grounding Source
-
-Use the injected `<temporal_context>` block as the authoritative clock source:
-- `Current UTC time` is the canonical current instant (from assistant host clock).
-- `Current local time` + `Timezone` are the active local-calendar interpretation.
-- `User timezone` + `Timezone source` tell you whether local-time interpretation is user-specific or host fallback.
-
-When `User timezone: unknown` and the request is locale-specific (e.g. "at 3pm", "tomorrow morning", "tonight"), ask once for their timezone and then proceed.
-If the user confirms a timezone, suggest saving it in Settings -> Appearance -> User timezone so future reminders resolve correctly without re-asking.
-
-## Relative Time Parsing
-
-When the user says "in X minutes/hours", compute the ISO 8601 timestamp yourself:
-- Take `Current UTC time` (or `Current local time` in the active `Timezone`)
-- Add the offset
-- Format as ISO 8601 with timezone: `2025-03-15T09:05:00-05:00`
-- Pass to `reminder_create` as `fire_at`
-
-### Anchored & Ambiguous Relative Time
-
-Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
-
-**Resolution rules (in priority order):**
-
-1. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2:10"), interpret offset-style phrases ("the 45 minute mark", "20 minutes in", "when I hit an hour") as `start_time + offset`. This takes precedence because the conversational anchor overrides any wall-clock interpretation.
-
-2. **Clock-position expressions** — when no start time is in context, map directly to a wall-clock time:
-   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
-   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
-   - "the half-hour mark" / "half past" → nearest upcoming :30
-   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
-   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
-
-3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
-
-**Examples:**
-- "meeting started at 2:10, remind me at the 45 minute mark" → 2:55 PM (start + 45 min)
-- "20 minutes in, I started at 2pm" → 2:20 PM (start + 20 min)
-- "at the 45 min mark" (no start time, now: 9:39) → 9:45 AM (wall-clock)
-- "at the 45 min mark" (no start time, now: 9:50) → 10:45 AM (wall-clock, next hour)
-- "top of the hour" (now: 9:39) → 10:00 AM
-- "at noon" → 12:00 PM today
-- "at the hour mark" with no start time → ask for clarification
-
-## "Remind me to X" Disambiguation
-
-The word "remind" is ambiguous. Route based on whether a time is specified:
-
-| User says | Time present? | Tool |
-|-----------|--------------|------|
-| "Remind me to buy milk" | No | `task_list_add` |
-| "Remind me to buy milk at 5pm" | Yes | `reminder_create` |
-| "Remind me in 10 minutes to check the oven" | Yes (relative) | `reminder_create` |
-| "Remind me every morning to take vitamins" | Yes (recurring) | `schedule_create` |
-
-## Reminder Modes
-
-`reminder_create` supports two 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
-
-Use `notify` for simple alerts. Use `execute` when the reminder should trigger the assistant to do something (e.g., "in 30 minutes, check if the build passed").
-
-## Reminder Routing
-
-`reminder_create` supports a `routing_intent` parameter that controls how the reminder is delivered at trigger time:
-- **`single_channel`** — deliver to one best channel
-- **`multi_channel`** — deliver to a subset of channels
-- **`all_channels`** (default) — deliver to every available channel
-
-You can also pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions).
-
-### Routing Defaults
-
-Use the following heuristics to pick `routing_intent`:
-
-- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
-- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
-- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
-  ```
-  routing_hints: { preferred_channels: ["vellum"] }
-  routing_intent: "all_channels"
-  ```
-- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
-
-### Examples
-
-| Scenario | routing_intent | routing_hints |
-|---|---|---|
-| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
-| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
-| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
-| No channel preference expressed | `all_channels` | `{}` |
-
-## Tool Summary
-
-| Tool | Timing | Recurrence | Purpose |
-|------|--------|------------|---------|
-| `reminder_create` | Future time (one-shot) | No | Timed notification or timed autonomous action |
-| `schedule_create` | Recurring pattern | Yes (cron/RRULE) | Recurring automated jobs |
-| `send_notification` | **Immediate only** | No | Alert the user right now |
-| `task_list_add` | **No time trigger** | No | Track work in the task queue |

package/src/config/bundled-skills/twilio-setup/SKILL.md

@@ -1,232 +0,0 @@
----
-name: twilio-setup
-description: Configure Twilio credentials and phone numbers for voice calls
-compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"📱","vellum":{"display-name":"Twilio Setup","user-invocable":true,"includes":["public-ingress"]}}
----
-
-You are helping your user configure Twilio for voice calls. Walk through each step below.
-
-## Value Classification
-
-Before you begin, understand how each Twilio value is stored:
-
-| Value        | Type       | Storage method                                | Secret? |
-| ------------ | ---------- | --------------------------------------------- | ------- |
-| Account SID  | Config     | `assistant config set twilio.accountSid`      | No      |
-| Auth Token   | Credential | `assistant credentials set twilio:auth_token` | **Yes** |
-| Phone Number | Config     | `assistant config set twilio.phoneNumber`     | No      |
-
-- **Config values** (Account SID, Phone Number) are non-sensitive identifiers. Collect them via normal conversation -- the user can paste them in chat or you can use `AskUserQuestion`.
-**Auth Token** is a secret. Collect it securely via `credential_store` prompt -- never accept it pasted in plaintext chat.
-
-## Retrieving Twilio Credentials
-
-Many steps below require the Account SID and Auth Token. Retrieve them with:
-
-```bash
-TWILIO_SID=$(assistant config get twilio.accountSid)
-TWILIO_TOKEN=$(assistant credentials reveal twilio:auth_token)
-```
-
-# Checking Current Configuration
-
-You can determine whether Twilio has been fully set up by checking to see that all the following config and credential values have been set:
-
-```bash
-assistant config get twilio.accountSid
-assistant credentials inspect twilio:auth_token --json  # check "hasSecret" field
-assistant config get twilio.phoneNumber
-```
-
-- If all three config values are non-empty -- Twilio is fully configured. Offer to show status or reconfigure.
-- Otherwise, continue to the missing steps.
-
-# Twilio Setup Steps
-
-Follow the steps below in order to fully configure Twilio in preparation to make phone calls.
-
-## Step 1: Check Current Configuration
-
-Refer to "Checking Current Configuration" above to see the current state of the user's Twilio setup. If Twilio appears to be fully configured. Offer to show status or reconfigure. Otherwise, continue to the missing steps below.
-
-## Step 2: Collect and Store Credentials
-
-Tell the user: **"You'll need a Twilio account. Sign up at https://www.twilio.com/try-twilio -- it's free to start and includes trial credit."**
-
-They need two values from the Twilio Console dashboard (https://console.twilio.com):
-
-- **Account SID** -- visible on the dashboard, starts with `AC` (this is not a secret value and can be collected conversationally)
-- **Auth Token** -- click "Show" to reveal (this is a secret value and should be collected securely)
-
-### Collect Account SID
-
-Ask the user for their Account SID. This is NOT a secret value, so the user should be encouraged to comfortable paste it into the chat directly. Once they have, store it as a config value:
-
-```bash
-assistant config set twilio.accountSid "<Account SID from user>"
-```
-
-### Collect Auth Token
-
-Ask the user for their Auth Token. This IS a secret value, so the user should be prompted to enter the value securely. Do NOT ask them to provide it in the chat. Once they have, store it as a credential:
-
-- Call `credential_store` with `action: "prompt"`, `service: "twilio"`, `field: "auth_token"`, `label: "Twilio Auth Token"`, `description: "Enter your Auth Token from the Twilio Console dashboard (click 'Show' to reveal it)"`, `placeholder: "your_auth_token"`.
-
-Confirm it has been stored successfully:
-
-```bash
-assistant credentials inspect "twilio:auth_token"
-```
-
-If credentials are invalid, Twilio API calls in Step 3 will fail -- ask the user to re-enter.
-
-## Step 3: Get a Phone Number
-
-The assistant needs a phone number for voice calls. Three options:
-
-### Option A: Use an Existing Number
-
-You should assume this option if the user had just created their Twilio account. Trial accounts come with one free number.
-
-Retrieve credentials, then list numbers on the account:
-
-```bash
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers.json"
-```
-
-Present the `incoming_phone_numbers` array. Let the user choose.
-
-### Option B: Provision a New Number
-
-Retrieve credentials (see "Retrieving Twilio Credentials" above), then:
-
-**Search for available numbers:**
-
-```bash
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/AvailablePhoneNumbers/US/Local.json?VoiceEnabled=true&AreaCode=415"
-```
-
-- `AreaCode` is optional -- ask the user if they have a preference
-- Replace `US` with another country code if needed
-
-Present the first few results from the `available_phone_numbers` array (show `phone_number` and `friendly_name`).
-
-**Purchase the chosen number:**
-
-```bash
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" -X POST \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers.json" \
-  -d "PhoneNumber=+14155551234"
-```
-
-Note the `sid` field (starts with `PN`) from the response -- needed for webhook setup in Step 4.
-
-### Option C: Manual Entry
-
-If the user already has a number and knows it, skip the API calls. They can paste it directly in chat.
-
-### Save the phone number
-
-After choosing a number via any option, store it as a config value:
-
-```bash
-assistant config set twilio.phoneNumber "+14155551234"
-```
-
-## Step 4: Set Up Public Ingress and Webhooks
-
-### Verify Public Ingress is Set Up
-
-Twilio needs a publicly reachable URL for voice webhooks. Load the `public-ingress` skill to determine whether a public ingress has been configured and walk the user through setting one up if not.
-
-### Configure Twilio Webhooks
-
-Set webhook URLs on the phone number so Twilio routes traffic to the assistant.
-
-Retrieve credentials and config values:
-
-```bash
-TWILIO_SID=$(assistant config get twilio.accountSid)
-TWILIO_TOKEN=$(assistant credentials reveal twilio:auth_token)
-PUBLIC_URL=$(assistant config get ingress.publicBaseUrl)
-PHONE_NUMBER=$(assistant config get twilio.phoneNumber)
-```
-
-Look up the phone number's SID:
-
-```bash
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers.json?PhoneNumber=$PHONE_NUMBER"
-```
-
-Note the `sid` field (starts with `PN`) from the matching entry, then update webhooks:
-
-```bash
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" -X POST \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers/$PHONE_SID.json" \
-  -d "VoiceUrl=$PUBLIC_URL/webhooks/twilio/voice" \
-  -d "StatusCallback=$PUBLIC_URL/webhooks/twilio/status"
-```
-
-
-## Clearing Credentials
-
-To disconnect Twilio:
-
-```bash
-assistant credentials delete twilio:auth_token
-assistant config set twilio.accountSid ""
-```
-
-Phone number assignments are preserved. Voice calls will stop until credentials are reconfigured.
-
-## Troubleshooting
-
-### "Twilio credentials not configured"
-
-Run Steps 2 and 3.
-
-### "No phone number assigned"
-
-Run Step 3.
-
-### Phone number provisioning fails
-
-- Verify credentials are correct
-- Trial accounts may already have a free number -- check "Active Numbers" in the Console
-- Ensure the account has sufficient balance
-
-### Calls fail after setup
-
-- Verify ingress is running: `assistant config get ingress.publicBaseUrl`
-- For calls, ensure `calls.enabled` is `true`
-- Trial accounts can only reach verified numbers
-
-### Incoming calls not reaching the assistant
-
-Webhooks on the Twilio phone number may not match the current ingress URL. This happens when ngrok restarts with a new URL or webhooks were never configured.
-
-**Diagnose** -- fetch the number's current webhooks and compare to the expected URL:
-
-```bash
-TWILIO_SID=$(assistant config get twilio.accountSid)
-TWILIO_TOKEN=$(assistant credentials reveal twilio:auth_token)
-PUBLIC_URL=$(assistant config get ingress.publicBaseUrl)
-PHONE_NUMBER=$(assistant config get twilio.phoneNumber)
-
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers.json?PhoneNumber=$PHONE_NUMBER"
-```
-
-Check that `voice_url` and `status_callback` start with the current `ingress.publicBaseUrl`. If they don't match, update them:
-
-```bash
-PHONE_SID=<PN sid from the response above>
-curl -s -u "$TWILIO_SID:$TWILIO_TOKEN" -X POST \
-  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_SID/IncomingPhoneNumbers/$PHONE_SID.json" \
-  -d "VoiceUrl=$PUBLIC_URL/webhooks/twilio/voice" \
-  -d "StatusCallback=$PUBLIC_URL/webhooks/twilio/status"
-```