@vellumai/assistant 0.4.11 → 0.4.13

package/src/config/{vellum-skills → bundled-skills}/sms-setup/SKILL.md

@@ -2,7 +2,7 @@
 name: "SMS Setup"
 description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
 user-invocable: true
-metadata: {"vellum": {"emoji": "\ud83d\udce8"}}
+metadata: { "vellum": { "emoji": "\ud83d\udce8" } }
 ---
 
 You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow.
@@ -30,7 +30,7 @@ If SMS baseline is not ready (missing credentials, phone number, or ingress), lo
 skill_load skill=twilio-setup
 ```
 
-Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."*
+Tell the user: _"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."_
 
 After twilio-setup completes, re-check readiness by calling the config endpoint again:
 
@@ -53,6 +53,7 @@ curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/sms/compliance" \
 ```
 
 Examine the compliance results:
+
 - If all checks pass, proceed to Step 4.
 - If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow.
 
@@ -71,18 +72,18 @@ The response includes a `compliance` object with `numberType`, `tollfreePhoneNum
 
 **Step 3b: Collect user information.** Collect the following from the user (assume individual/sole proprietor by default):
 
-| Field | `verificationParams` key | Notes |
-|---|---|---|
-| Name | `businessName` | Can be personal name |
-| Business type | `businessType` | Use `SOLE_PROPRIETOR` for individuals. Valid values: `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR`, `NON_PROFIT`, `GOVERNMENT` |
-| Website | `businessWebsite` | LinkedIn or personal site is fine |
-| Notification email | `notificationEmail` | Where Twilio sends status updates |
-| Use case category | `useCaseCategories` | Array, e.g. `["ACCOUNT_NOTIFICATIONS"]` |
-| Use case summary | `useCaseSummary` | Plain English description |
-| Message volume | `messageVolume` | Must be one of: `10`, `100`, `1,000`, `10,000`, `100,000`, `250,000`, `500,000`, `750,000`, `1,000,000`, `5,000,000`, `10,000,000+` |
-| Sample message | `productionMessageSample` | A realistic example message |
-| Opt-in type | `optInType` | `VERBAL`, `WEB_FORM`, `PAPER_FORM`, `VIA_TEXT`, `MOBILE_QR_CODE` |
-| Opt-in image URL | `optInImageUrls` | Array of URLs showing opt-in mechanism (can be website URL) |
+| Field              | `verificationParams` key  | Notes                                                                                                                                 |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Name               | `businessName`            | Can be personal name                                                                                                                  |
+| Business type      | `businessType`            | Use `SOLE_PROPRIETOR` for individuals. Valid values: `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR`, `NON_PROFIT`, `GOVERNMENT` |
+| Website            | `businessWebsite`         | LinkedIn or personal site is fine                                                                                                     |
+| Notification email | `notificationEmail`       | Where Twilio sends status updates                                                                                                     |
+| Use case category  | `useCaseCategories`       | Array, e.g. `["ACCOUNT_NOTIFICATIONS"]`                                                                                               |
+| Use case summary   | `useCaseSummary`          | Plain English description                                                                                                             |
+| Message volume     | `messageVolume`           | Must be one of: `10`, `100`, `1,000`, `10,000`, `100,000`, `250,000`, `500,000`, `750,000`, `1,000,000`, `5,000,000`, `10,000,000+`   |
+| Sample message     | `productionMessageSample` | A realistic example message                                                                                                           |
+| Opt-in type        | `optInType`               | `VERBAL`, `WEB_FORM`, `PAPER_FORM`, `VIA_TEXT`, `MOBILE_QR_CODE`                                                                      |
+| Opt-in image URL   | `optInImageUrls`          | Array of URLs showing opt-in mechanism (can be website URL)                                                                           |
 
 The `tollfreePhoneNumberSid` is returned by the compliance status response in the `compliance` object. Use `compliance.tollfreePhoneNumberSid` from the Step 3a response as the value for `tollfreePhoneNumberSid` when submitting. Do NOT ask for EIN, business registration number, or business registration authority. Explain that Twilio labels some fields as "business" fields even for individual submitters.
 
@@ -140,6 +141,7 @@ curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/sms/complia
 After deletion, return to Step 3b to collect information and resubmit. Warn the user that deleting resets their position in the review queue.
 
 **Common errors:**
+
 - `"Customer profiles submitted with verifications must be either ISV Starters or Secondary Customer Profiles"` — The number is linked to a Primary Customer Profile in Trust Hub, which blocks toll-free verification. Tell the user and suggest they resolve the profile assignment in the Twilio Console.
 - Missing required fields — The endpoint validates and reports which fields are missing.
 - Invalid enum values — The endpoint validates `optInType`, `messageVolume`, and `useCaseCategories` and reports valid values.
@@ -152,19 +154,19 @@ After deletion, return to Step 3b to collect information and resubmit. Warn the
 
 Now link the user's phone number as the trusted SMS guardian. Tell the user: "Now let's verify your guardian identity for SMS. This links your phone number as the trusted guardian for SMS messaging."
 
-Install and load the **guardian-verify-setup** skill to handle the verification flow:
+Load the **guardian-verify-setup** skill to handle the verification flow:
 
-- Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "guardian-verify-setup"`.
-- Then call `skill_load` with `skill: "guardian-verify-setup"`.
+- Call `skill_load` with `skill_id: "guardian-verify-setup"` to load the dependency skill.
 
 When invoking the skill, indicate the channel is `sms`. The guardian-verify-setup skill manages the full outbound verification flow, including:
+
 - Collecting the user's phone number as the destination (accepts any common format -- the API normalizes to E.164)
 - Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start` with `channel: "sms"`
 - Sending a 6-digit code to the phone number that the user must reply with from the SMS channel
 - Checking guardian status to confirm the binding was created
 - Handling resend, cancel, and error cases
 
-Tell the user: *"I've loaded the guardian verification guide. It will walk you through linking your phone number as the trusted SMS guardian."*
+Tell the user: _"I've loaded the guardian verification guide. It will walk you through linking your phone number as the trusted SMS guardian."_
 
 **Note:** Guardian verification is optional but recommended. If the user declines or wants to skip, proceed to Step 4 without blocking.
 
@@ -172,7 +174,7 @@ Tell the user: *"I've loaded the guardian verification guide. It will walk you t
 
 Run a test SMS to verify end-to-end delivery:
 
-Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"*
+Tell the user: _"Let's send a test SMS to verify everything works. What phone number should I send the test to?"_
 
 **Important:** If toll-free verification is pending (not yet approved), inform the user that test messages may be silently dropped by carriers even though Twilio accepts them. Offer to attempt the test anyway, but set expectations.
 
@@ -189,7 +191,8 @@ curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/sms/test" \
 ```
 
 Report the result honestly:
-- If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes. If verification is still pending, carriers may silently drop the message."*
+
+- If the send succeeds: _"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes. If verification is still pending, carriers may silently drop the message."_
 - If the send fails: report the error and suggest troubleshooting steps
 
 ### SMS Diagnostics
@@ -209,7 +212,8 @@ This runs a comprehensive health diagnostic, checking channel readiness, complia
 After completing (or skipping) the test, present a clear summary:
 
 **If everything passed:**
-*"SMS is ready! Here's your setup status:"*
+_"SMS is ready! Here's your setup status:"_
+
 - Twilio credentials: configured
 - Phone number: {number}
 - Ingress: configured
@@ -217,17 +221,20 @@ After completing (or skipping) the test, present a clear summary:
 - Test send: {result}
 
 **If there are blockers:**
-*"SMS setup is partially complete. Here's what still needs attention:"*
+_"SMS setup is partially complete. Here's what still needs attention:"_
+
 - List each blocker with the specific next action
 
 ## Troubleshooting
 
 If the user returns to this skill after initial setup:
+
 1. Always start with Step 1 (readiness check) to assess current state
 2. Skip steps that are already complete
 3. Focus on the specific issue the user is experiencing
 
 Common issues:
+
 - **"Messages not delivering"** — Check compliance status (toll-free verification), verify the number isn't flagged
 - **"Twilio error on send"** — Check credentials, phone number assignment, and ingress
 - **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers

package/src/config/{vellum-skills → bundled-skills}/telegram-setup/SKILL.md

@@ -3,7 +3,7 @@ name: "Telegram Setup"
 description: "Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage"
 user-invocable: true
 includes: ["public-ingress"]
-metadata: {"vellum": {"emoji": "\ud83e\udd16"}}
+metadata: { "vellum": { "emoji": "\ud83e\udd16" } }
 ---
 
 You are helping your user connect a Telegram bot to the Vellum Assistant gateway. Telegram webhooks are received exclusively by the gateway (the public ingress boundary) — they never hit the assistant runtime directly. When this skill is invoked, walk through each step below using only existing tools.
@@ -28,6 +28,7 @@ Before beginning setup, verify these conditions are met:
 ### Step 1: Collect the Bot Token Securely
 
 Collect the bot 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"`, and `placeholder: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`.
 
 The token is collected securely via a system-level prompt and is never exposed in plaintext chat.
@@ -44,6 +45,7 @@ curl -sf -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/setup" \
 ```
 
 This endpoint automatically:
+
 - Retrieves the bot token from secure storage
 - Validates the token by calling the Telegram `getMe` API
 - Stores the bot token with bot username metadata
@@ -65,12 +67,12 @@ If the webhook secret changes (e.g., secret rotation), the gateway's credential
 
 Now link the user's Telegram account as the trusted guardian for this bot. Tell the user: "Now let's verify your guardian identity. This links your Telegram account as the trusted guardian for this bot."
 
-Install and load the **guardian-verify-setup** skill to handle the verification flow:
+Load the **guardian-verify-setup** skill to handle the verification flow:
 
-- Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "guardian-verify-setup"`.
-- Then call `skill_load` with `skill: "guardian-verify-setup"`.
+- Call `skill_load` with `skill_id: "guardian-verify-setup"` to load the dependency skill.
 
 The guardian-verify-setup skill manages the full outbound verification flow for Telegram, including:
+
 - Collecting the user's Telegram chat ID or @handle as the destination
 - Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start` with `channel: "telegram"`
 - Handling the bootstrap deep-link flow when the user provides an @handle (the response includes a `telegramBootstrapUrl` that the user must click before receiving the code)
@@ -78,7 +80,7 @@ The guardian-verify-setup skill manages the full outbound verification flow for
 - Checking guardian status to confirm the binding was created
 - Handling resend, cancel, and error cases
 
-Tell the user: *"I've loaded the guardian verification guide. It will walk you through linking your Telegram account as the trusted guardian."*
+Tell the user: _"I've loaded the guardian verification guide. It will walk you through linking your Telegram account as the trusted guardian."_
 
 After the guardian-verify-setup skill completes (or the user skips), continue to Step 5.
 
@@ -111,6 +113,7 @@ If the binding is absent and the user said they completed the verification:
 ### Step 7: Report Success
 
 Summarize what was done:
+
 - Bot verified and credentials stored securely
 - Webhook registration: handled automatically by the gateway
 - Bot commands registered: /new
@@ -136,17 +139,17 @@ These limitations apply to all Telegram bots regardless of configuration. Future
 
 The following steps are now **automated** by the gateway and CLI:
 
-| Step | Status | Details |
-|------|--------|---------|
-| Webhook registration | Automated | The gateway reconciles the webhook URL on startup and when credentials change |
+| Step                  | Status                       | Details                                                                                         |
+| --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| Webhook registration  | Automated                    | The gateway reconciles the webhook URL on startup and when credentials change                   |
 | Routing configuration | Automated (single-assistant) | The CLI sets `GATEWAY_UNMAPPED_POLICY=default` and `GATEWAY_DEFAULT_ASSISTANT_ID` automatically |
-| Credential detection | Automated | The gateway watches the credential vault for changes |
+| Credential detection  | Automated                    | The gateway watches the credential vault for changes                                            |
 
 The following steps still require **manual** action:
 
-| Step | Details |
-|------|---------|
-| Bot token from @BotFather | User must create a bot and provide the token via secure prompt |
+| Step                                       | Details                                                                                            |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| Bot token from @BotFather                  | User must create a bot and provide the token via secure prompt                                     |
 | Bot configuration and command registration | Configured via the setup skill (Step 2 above) using the `/v1/integrations/telegram/setup` endpoint |
-| Guardian verification | Handled via the guardian-verify-setup skill using the outbound verification flow (Step 4 above) |
-| Multi-assistant routing | Requires manual `GATEWAY_ASSISTANT_ROUTING_JSON` configuration |
+| Guardian verification                      | Handled via the guardian-verify-setup skill using the outbound verification flow (Step 4 above)    |
+| Multi-assistant routing                    | Requires manual `GATEWAY_ASSISTANT_ROUTING_JSON` configuration                                     |

package/src/config/{vellum-skills → bundled-skills}/twilio-setup/SKILL.md

@@ -3,7 +3,7 @@ name: "Twilio Setup"
 description: "Configure Twilio credentials and phone numbers for voice calls and SMS messaging"
 user-invocable: true
 includes: ["public-ingress"]
-metadata: {"vellum": {"emoji": "\ud83d\udcf1"}}
+metadata: { "vellum": { "emoji": "\ud83d\udcf1" } }
 ---
 
 You are helping your user configure Twilio for voice calls and SMS messaging. Twilio is the shared telephony provider for both the **phone-calls** and **SMS messaging** capabilities. When this skill is invoked, walk through each step below using the Twilio HTTP control-plane endpoints and existing tools.
@@ -30,6 +30,7 @@ For voice call setup after Twilio is configured, use `phone-calls` + `call_start
 ## Overview
 
 This skill manages the full Twilio lifecycle:
+
 - **Credential storage** — Account SID and Auth Token
 - **Phone number provisioning** — Buy a new number directly from Twilio
 - **Phone number assignment** — Assign an existing Twilio number to the assistant
@@ -42,16 +43,19 @@ All operations go through the Twilio HTTP control-plane endpoints on the gateway
 In a multi-assistant environment (multiple assistants sharing the same daemon), some actions are **assistant-scoped** while others are **global** (shared across all assistants):
 
 **Global actions** (ignore `assistantId` — credentials are shared across all assistants):
+
 - `POST /v1/integrations/twilio/credentials` — Stores Account SID and Auth Token in global secure storage (`credential:twilio:*` keys). All assistants share the same Twilio account credentials.
 - `DELETE /v1/integrations/twilio/credentials` — Removes the globally stored Account SID and Auth Token. This affects all assistants.
 
 **Assistant-scoped actions** (use `assistantId` query parameter to scope phone number configuration per assistant):
+
 - `GET /v1/integrations/twilio/config` — Returns the phone number assigned to the specified assistant.
 - `POST /v1/integrations/twilio/numbers/assign` — Assigns a phone number to a specific assistant via the per-assistant mapping.
 - `POST /v1/integrations/twilio/numbers/provision` — Provisions a new number and assigns it to the specified assistant.
 - `GET /v1/integrations/twilio/numbers` — Lists all phone numbers on the shared Twilio account (uses global credentials).
 
 Include `assistantId` as a query parameter in assistant-scoped requests whenever:
+
 - Multiple assistants share the same Twilio account but use different phone numbers
 - You want to ensure configuration changes only affect a specific assistant
 - The user has explicitly selected or referenced a particular assistant
@@ -69,6 +73,7 @@ curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/config" \
 ```
 
 The response includes:
+
 - `hasCredentials` — whether Account SID and Auth Token are stored
 - `phoneNumber` — the currently assigned phone number (if any)
 
@@ -124,6 +129,7 @@ curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/numbers/provi
 The endpoint provisions the number via the Twilio API, automatically assigns it to the assistant (persisting to both secure storage and config), and configures Twilio webhooks (voice, status callback, SMS) if a public ingress URL is available. The response includes the new `phoneNumber`. No separate assign call is needed.
 
 **Webhook auto-configuration:** When `ingress.publicBaseUrl` is configured, the endpoint automatically sets the following webhooks on the Twilio phone number:
+
 - Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
 - Voice status callback: `{publicBaseUrl}/webhooks/twilio/status`
 - SMS webhook: `{publicBaseUrl}/webhooks/twilio/sms`
@@ -192,6 +198,7 @@ skill_load skill=public-ingress
 ```
 
 **Twilio webhook endpoints (auto-configured on provision/assign):**
+
 - Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
 - Voice status callback: `{publicBaseUrl}/webhooks/twilio/status`
 - ConversationRelay WebSocket: `{publicBaseUrl}/webhooks/twilio/relay` (wss://)
@@ -210,6 +217,7 @@ curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/config" \
 ```
 
 Confirm:
+
 - `hasCredentials` is `true`
 - `phoneNumber` is set to the expected number
 
@@ -219,12 +227,12 @@ Tell the user: **"Twilio is configured. Your assistant's phone number is {phoneN
 
 Now link the user's phone number as the trusted guardian for SMS and/or voice channels. Tell the user: "Now let's verify your guardian identity. This links your phone number as the trusted guardian for messaging and calls."
 
-Install and load the **guardian-verify-setup** skill to handle the verification flow:
+Load the **guardian-verify-setup** skill to handle the verification flow:
 
-- Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "guardian-verify-setup"`.
-- Then call `skill_load` with `skill: "guardian-verify-setup"`.
+- Call `skill_load` with `skill_id: "guardian-verify-setup"` to load the dependency skill.
 
 The guardian-verify-setup skill manages the full outbound verification flow for **one channel at a time** (sms, voice, or telegram). Each invocation handles:
+
 - Collecting the user's phone number as the destination (accepts any common format -- the API normalizes to E.164)
 - Starting the outbound verification session via the gateway endpoint `POST /v1/integrations/guardian/outbound/start`
 - For **SMS**: sending a 6-digit code to the phone number that the user must reply with from the SMS channel
@@ -234,13 +242,14 @@ The guardian-verify-setup skill manages the full outbound verification flow for
 
 **If the user wants to verify both SMS and voice**, load the skill twice -- once for SMS and once for voice. Each channel requires its own separate verification session.
 
-Tell the user: *"I've loaded the guardian verification guide. It will walk you through linking your phone number as the trusted guardian. We'll verify one channel at a time."*
+Tell the user: _"I've loaded the guardian verification guide. It will walk you through linking your phone number as the trusted guardian. We'll verify one channel at a time."_
 
 After the guardian-verify-setup skill completes verification for a channel, load it again for the next channel if needed. Once all desired channels are verified (or the user skips), continue to Step 6.
 
 **Note:** Guardian verification is optional but recommended. If the user declines or wants to skip, proceed to Step 6 without blocking.
 
 To re-check guardian status later, query the channel(s) that were verified:
+
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
 # Check SMS guardian status
@@ -258,6 +267,7 @@ Check the status for whichever channel(s) the user actually verified (SMS, voice
 Now that Twilio is configured, the user can enable the features that depend on it:
 
 **For voice calls:**
+
 ```bash
 vellum config set calls.enabled true
 ```
@@ -282,22 +292,27 @@ This removes the stored Account SID and Auth Token. Phone number assignments are
 ## Troubleshooting
 
 ### "Twilio credentials not configured"
+
 Run Steps 2 and 3 to store credentials and assign a phone number.
 
 ### "No phone number assigned"
+
 Run Step 3 to provision or assign a phone number.
 
 ### Phone number provisioning fails
+
 - Verify Twilio credentials are correct
 - On trial accounts, you may already have a free number — check "Active Numbers" in the Console
 - Ensure the Twilio account has sufficient balance for paid accounts
 
 ### Calls/SMS fail after setup
+
 - Verify public ingress is running (`ingress.publicBaseUrl` must be set)
 - For calls, ensure `calls.enabled` is `true`
 - On trial accounts, outbound calls and SMS can only reach verified numbers
 
 ### "Number not found" when assigning
+
 - The number must be owned by the same Twilio account
 - Use the list numbers endpoint to see available numbers
 - Ensure the number is in E.164 format (`+` followed by country code and number)