@vellumai/assistant 0.3.4 → 0.3.5

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

@@ -18,6 +18,27 @@ This skill manages the full Twilio lifecycle:
 
 All operations go through the `twilio_config` IPC handler on the daemon, which validates inputs, stores credentials securely, and manages phone number state.
 
+### Multi-Assistant Setups
+
+In a multi-assistant environment (multiple assistants sharing the same daemon), some `twilio_config` actions are **assistant-scoped** while others are **global** (shared across all assistants):
+
+**Global actions** (ignore `assistantId` — credentials are shared across all assistants):
+- `set_credentials` — Stores Account SID and Auth Token in global secure storage (`credential:twilio:*` keys). All assistants share the same Twilio account credentials.
+- `clear_credentials` — Removes the globally stored Account SID and Auth Token. This affects all assistants.
+
+**Assistant-scoped actions** (use `assistantId` to scope phone number configuration per assistant):
+- `get` — Returns the phone number assigned to the specified assistant (falls back to the legacy global number if no per-assistant mapping exists).
+- `assign_number` — Assigns a phone number to a specific assistant via the per-assistant mapping.
+- `provision_number` — Provisions a new number and assigns it to the specified assistant.
+- `list_numbers` — Lists all phone numbers on the shared Twilio account (uses global credentials).
+
+Include `assistantId` in assistant-scoped actions 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
+
+All IPC examples below include the optional `assistantId` field in assistant-scoped actions. Omit it in single-assistant setups. For global actions (`set_credentials`, `clear_credentials`), the `assistantId` field is accepted but ignored.
+
 ## Step 1: Check Current Configuration
 
 First, check whether Twilio is already configured by sending the `twilio_config` IPC message with `action: "get"`:
@@ -25,7 +46,8 @@ First, check whether Twilio is already configured by sending the `twilio_config`
 ```json
 {
   "type": "twilio_config",
-  "action": "get"
+  "action": "get",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -62,6 +84,8 @@ After both credentials are collected, retrieve them from secure storage and pass
 
 Both `accountSid` and `authToken` are required — the daemon validates the credentials against the Twilio API before storing them. If credentials are invalid, the daemon returns an error. Tell the user and ask them to re-enter via the secure prompt.
 
+**Note:** `set_credentials` is a global operation — credentials are stored once and shared across all assistants. The `assistantId` field is accepted but ignored.
+
 ## Step 3: Get a Phone Number
 
 The assistant needs a phone number to make calls and send SMS. There are two paths:
@@ -75,7 +99,8 @@ If the user wants to buy a new number through Twilio, send:
   "type": "twilio_config",
   "action": "provision_number",
   "areaCode": "415",
-  "country": "US"
+  "country": "US",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -100,7 +125,8 @@ If the user already has a Twilio phone number, first list available numbers:
 ```json
 {
   "type": "twilio_config",
-  "action": "list_numbers"
+  "action": "list_numbers",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -112,7 +138,8 @@ Then assign the chosen number:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -132,7 +159,8 @@ Then assign it through the IPC:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -181,7 +209,8 @@ Now link the user's phone number as the trusted SMS guardian for this assistant.
 {
   "type": "guardian_verification",
   "action": "create_challenge",
-  "channel": "sms"
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -195,7 +224,8 @@ Now link the user's phone number as the trusted SMS guardian for this assistant.
 {
   "type": "guardian_verification",
   "action": "status",
-  "channel": "sms"
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -232,7 +262,9 @@ If the user wants to disconnect Twilio, send:
 }
 ```
 
-This removes the stored Account SID and Auth Token. Your phone number assignment will be preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+This removes the stored Account SID and Auth Token. Phone number assignments are preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+
+**Note:** `clear_credentials` is a global operation — it removes credentials for all assistants, not just the current one. The `assistantId` field is accepted but ignored. In multi-assistant setups, warn the user that clearing credentials will affect all assistants sharing this Twilio account.
 
 ## Troubleshooting