@vellumai/assistant 0.4.2 → 0.4.4

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -17,7 +17,15 @@ Twilio credentials and phone number configuration are shared between voice calls
 
 The twilio-setup skill handles credential storage, phone number provisioning/assignment, and public ingress setup. Once complete, return here to enable the calls feature and start making calls.
 
-If Twilio is already configured (check `twilio_config` with `action: "get"`), skip directly to **Step 5: Enable Calls** below.
+Check if Twilio is already configured:
+
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/config" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+If `hasCredentials` is `true` and `phoneNumber` is set, skip directly to **Step 5: Enable Calls** below.
 
 ## Overview
 
@@ -58,65 +66,48 @@ The user's assistant gets its own personal phone number through Twilio. All impl
 First, check whether Twilio is already configured:
 
 ```bash
-vellum config get calls.enabled
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/config" \
+  -H "Authorization: Bearer $TOKEN"
 ```
 
-Also check for existing credentials:
+Also check calls feature status:
 
 ```bash
-credential_store action=list
+vellum config get calls.enabled
 ```
 
-Look for entries with service `twilio` and fields `account_sid`, `auth_token`, and `phone_number`.
-
-If all three credentials exist and `calls.enabled` is `true`, skip to the **Making Calls** section. If credentials are partially configured, skip to whichever step is still needed.
+If the config response shows `hasCredentials: true` and `phoneNumber` is set, and `calls.enabled` is `true`, skip to the **Making Calls** section. If credentials are partially configured, skip to whichever step is still needed.
 
 ## Step 2: Create a Twilio Account
 
 If the user doesn't have a Twilio account yet, guide them through setup:
 
 1. Tell the user: **"You'll need a Twilio account to make phone calls. Sign up at https://www.twilio.com/try-twilio — it's free to start and includes trial credit."**
-2. Once they have an account, they need three pieces of information:
+2. Once they have an account, they need two pieces of information:
    - **Account SID** — found on the Twilio Console dashboard at https://console.twilio.com
    - **Auth Token** — found on the same dashboard (click "Show" to reveal it)
-   - **Phone Number** — a Twilio phone number capable of making voice calls
-
-### Getting a Twilio Phone Number
-
-If the user doesn't have a Twilio phone number yet:
-
-1. Direct them to https://console.twilio.com/us1/develop/phone-numbers/manage/incoming
-2. Click **"Buy a Number"**
-3. Select a number with **Voice** capability enabled
-4. For trial accounts, Twilio provides one free number automatically — check "Active Numbers" first
 
-Tell the user: **"This will be your assistant's personal phone number — the number that shows up on caller ID when calls are placed."**
+Tell the user: **"The assistant will get its own personal phone number through Twilio — the number that shows up on caller ID when calls are placed."**
 
 ## Step 3: Store Twilio Credentials
 
-Once the user provides their credentials, store them securely using the `credential_store` tool. Ask the user to paste each value, then store them one at a time:
+**IMPORTANT — Secure credential collection only:** Never use credentials pasted in plaintext chat. Always collect credentials through the secure credential prompt flow:
 
-**Account SID:**
-```
-credential_store action=store service=twilio field=account_sid value=<their_account_sid>
-```
+- Call `credential_store` with `action: "prompt"`, `service: "twilio"`, `field: "account_sid"`, `label: "Twilio Account SID"`, `description: "Enter your Account SID from the Twilio Console dashboard"`, and `placeholder: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"`.
+- 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"`, and `placeholder: "your_auth_token"`.
 
-**Auth Token:**
-```
-credential_store action=store service=twilio field=auth_token value=<their_auth_token>
-```
+After both credentials are collected, send them to the gateway:
 
-**Phone Number** (must be in E.164 format, e.g. `+14155551234`):
-```
-credential_store action=store service=twilio field=phone_number value=<their_phone_number>
-```
-
-After storing, verify each credential was saved:
-```
-credential_store action=list
+```bash
+TOKEN=$(cat ~/.vellum/http-token)
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/credentials" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"accountSid":"<value from credential_store for twilio/account_sid>","authToken":"<value from credential_store for twilio/auth_token>"}'
 ```
 
-Confirm that entries for service `twilio` with fields `account_sid`, `auth_token`, and `phone_number` appear in the output.
+The endpoint validates the credentials against the Twilio API before storing them. If credentials are invalid, ask the user to re-enter via the secure prompt.
 
 **Important:** Credentials are stored in the OS keychain (macOS Keychain / Linux secret-service) or encrypted at rest. They are never logged or exposed in plaintext.
 
@@ -163,7 +154,7 @@ vellum config get calls.enabled
 
 Before making real calls, offer a quick verification:
 
-1. Confirm credentials are stored: all three Twilio credentials (`account_sid`, `auth_token`, `phone_number`) must be present
+1. Confirm credentials are stored: check the Twilio config endpoint for `hasCredentials: true` and `phoneNumber`
 2. Confirm ingress is running: `ingress.publicBaseUrl` must be set and the tunnel active
 3. Confirm calls are enabled: `calls.enabled` must be `true`
 
@@ -605,7 +596,7 @@ The following behavioral changes were introduced with the cross-channel guardian
 ## Troubleshooting
 
 ### "Twilio credentials not configured"
-Run Step 3 to store your Account SID, Auth Token, and Phone Number via `credential_store`.
+Run Step 3 to store your Account SID and Auth Token via the secure credential prompt flow, or load the `twilio-setup` skill.
 
 ### "Calls feature is disabled"
 Run `vellum config set calls.enabled true`.

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

@@ -17,7 +17,7 @@ OAuth uses the official X API v2. It is the most reliable connection method and
 
 - Supports: **post** and **reply**
 - Read-only operations (timeline, search, home, bookmarks, notifications, likes, followers, following, media) always use the browser path directly, regardless of the strategy setting.
-- Setup: Collect the OAuth Client ID (and optional Client Secret) from the user in chat using `credential_store` with `action: "prompt"` (canonical field names: `client_id`, `client_secret`), then initiate the `twitter_auth_start` IPC flow. See the **First-Use Decision Flow** for the full sequence.
+- Setup: Collect the OAuth Client ID (and optional Client Secret) from the user in chat using `credential_store` with `action: "prompt"` (canonical field names: `client_id`, `client_secret`), then initiate the `twitter_auth_start` flow. See the **First-Use Decision Flow** for the full sequence.
 - Set the strategy: `vellum x strategy set oauth`
 
 ### Browser session (no developer credentials needed)
@@ -56,7 +56,7 @@ When the user triggers a Twitter operation and no strategy has been configured y
 
 ### OAuth Setup Sequence
 
-When the user chooses OAuth, collect their X developer credentials conversationally using the secure UI. The OAuth flow delegates to the generic connect orchestrator via the `twitter_auth_start` IPC message (which internally uses the shared orchestrator while preserving Twitter-specific guards like integration-mode checks and refresh-token cleanup).
+When the user chooses OAuth, collect their X developer credentials conversationally using the secure UI. The OAuth flow delegates to the generic connect orchestrator, which resolves the Twitter provider profile, computes scopes via policy, opens the X authorization page in the user's browser, verifies the user's identity, and stores tokens. The orchestrator also manages stale refresh-token cleanup and enforces integration-mode guards.
 
 1. **Collect the Client ID securely:**
    Call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "client_id"`, `label: "X (Twitter) OAuth Client ID"`, `description: "Enter the Client ID from your X Developer App"`, and `placeholder: "your-client-id"`.
@@ -65,7 +65,7 @@ When the user chooses OAuth, collect their X developer credentials conversationa
    Ask the user if their X app uses a confidential client (has a Client Secret). If yes, call `credential_store` with `action: "prompt"`, `service: "integration:twitter"`, `field: "client_secret"`, `label: "X (Twitter) OAuth Client Secret"`, `description: "Enter the Client Secret from your X Developer App (leave blank if using a public client)"`, and `placeholder: "your-client-secret"`.
 
 3. **Initiate the OAuth flow:**
-   Send the `twitter_auth_start` IPC message. The handler delegates to the shared connect orchestrator, which resolves the Twitter provider profile, computes scopes via policy, opens the X authorization page in the user's browser, verifies the user's identity, and stores tokens. The handler also manages stale refresh-token cleanup and enforces integration-mode guards. Wait for the `twitter_auth_result` response.
+   Trigger the Twitter auth start flow. The connect orchestrator resolves the Twitter provider profile, computes scopes via policy, opens the X authorization page in the user's browser, verifies the user's identity, and stores tokens. Wait for the auth result.
 
 4. **Confirm success:**
    Tell the user: "Great, your X account is connected! You can always update these credentials from the Settings page."

package/src/config/bundled-skills/vercel-token-setup/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: "Vercel Token Setup"
+description: "Set up a Vercel API token for publishing apps using browser automation"
+includes: ["browser"]
+credential-setup-for: "vercel:api_token"
+metadata: {"vellum": {"emoji": "▲"}}
+---
+
+You are helping your user set up a Vercel API token so they can publish apps to the web.
+
+## Client Check
+
+Determine whether the user has browser automation available (macOS desktop app) or is on a non-interactive channel (Telegram, SMS, etc.).
+
+- **macOS desktop app**: Follow the **Automated Setup** path below.
+- **Telegram or other channel** (no browser automation): Follow the **Manual Setup for Channels** path below.
+
+---
+
+# Path A: Manual Setup for Channels (Telegram, SMS, etc.)
+
+When the user is on Telegram or any non-macOS client, walk them through a text-based setup. No browser automation is used — the user follows links and performs each action manually.
+
+### Channel Step 1: Confirm and Explain
+
+Tell the user:
+
+> **Setting up Vercel API Token**
+>
+> Since I can't automate the browser from here, I'll walk you through each step with direct links. You'll need:
+> 1. A Vercel account (free tier works)
+> 2. About 2 minutes
+>
+> Ready to start?
+
+If the user declines, acknowledge and stop.
+
+### Channel Step 2: Create the Token
+
+Tell the user:
+
+> **Step 1: Create an API token**
+>
+> Open this link to go to your Vercel tokens page:
+> https://vercel.com/account/tokens
+>
+> 1. Click **"Create"** (or **"Create Token"**)
+> 2. Set the token name to **"Vellum Assistant"**
+> 3. Select scope: **"Full Account"**
+> 4. Set expiration to the longest option available (or **"No Expiration"** if offered)
+> 5. Click **"Create Token"**
+>
+> A token value will appear — **copy it now**, as it's only shown once.
+
+### Channel Step 3: Store the Token
+
+Tell the user:
+
+> **Step 2: Send me the token**
+>
+> Please paste the token value into the secure prompt below.
+
+Present the secure prompt:
+
+```
+credential_store prompt:
+  service: "vercel"
+  field: "api_token"
+  label: "Vercel API Token"
+  description: "Paste the API token you just created on vercel.com"
+  placeholder: "Enter your Vercel API token"
+```
+
+Wait for the user to complete the prompt. Once received, store it:
+
+```
+credential_store store:
+  service: "vercel"
+  field: "api_token"
+  value: "<the token the user provided>"
+  allowedTools: ["publish_page", "unpublish_page"]
+  allowedDomains: ["api.vercel.com"]
+```
+
+### Channel Step 4: Done!
+
+> **Vercel is connected!** You can now publish apps to the web. Try clicking Publish on any app you've built.
+
+---
+
+# Path B: Automated Setup (macOS Desktop App)
+
+You will automate Vercel token creation via the browser while the user watches. The user's only manual action is signing in to Vercel (if needed) and one copy-paste for the token value.
+
+## Browser Interaction Principles
+
+Vercel's UI may change over time. Do NOT memorize or depend on specific element IDs, CSS selectors, or DOM structures. Instead:
+
+1. **Screenshot first, act second.** Before every interaction, take a `browser_screenshot` to see the current visual state. Use `browser_snapshot` to find interactive elements.
+2. **Adapt to what you see.** If a button's label or position differs from what you expect, use the screenshot to find the correct element.
+3. **Verify after every action.** After clicking, typing, or navigating, take a new screenshot to confirm the action succeeded.
+4. **Never assume DOM structure.** Use the snapshot to identify what's on the page and interact accordingly.
+5. **When stuck, screenshot and describe.** If you cannot find an expected element after 2 attempts, take a screenshot, describe what you see to the user, and ask for guidance.
+
+## Anti-Loop Guardrails
+
+Each step has a **retry budget of 3 attempts**. An attempt is one try at the step's primary action (e.g., clicking a button, filling a form). If a step fails after 3 attempts:
+
+1. **Stop trying.** Do not continue retrying the same approach.
+2. **Fall back to manual.** Tell the user what you were trying to do and ask them to complete that step manually in the browser. Give them the direct URL and clear text instructions.
+3. **Resume automation** at the next step once the user confirms the manual step is done.
+
+If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links.
+
+## Things That Do Not Work — Do Not Attempt
+
+These actions are technically impossible in the browser automation environment:
+
+- **Downloading files.** `browser_click` on a Download button does not save files to disk.
+- **Reading the token value from a screenshot.** The token IS visible in the creation dialog, but you MUST NOT attempt to read it from a screenshot — it is too easy to misread characters, and the value must be exact. Always use the `credential_store prompt` approach to let the user copy-paste it accurately.
+- **Clipboard operations.** You cannot copy/paste via browser automation.
+
+## Step 1: Single Upfront Confirmation
+
+Tell the user:
+
+> **Setting up your Vercel API token so we can publish your app...**
+>
+> Here's what will happen:
+> 1. **A browser opens** to your Vercel account settings
+> 2. **You sign in** (if not already signed in)
+> 3. **I create the token** — you just watch
+> 4. **One quick copy-paste** — I'll ask you to copy the token value into a secure prompt
+>
+> Takes about a minute. Ready?
+
+If the user declines, acknowledge and stop. No further confirmations are needed after this point.
+
+## Step 2: Open Vercel and Sign In
+
+**Goal:** The user is signed in and the Vercel tokens page is loaded.
+
+Navigate to `https://vercel.com/account/tokens`.
+
+Take a screenshot and snapshot to check the page state:
+- **Sign-in page:** Tell the user: "Please sign in to your Vercel account in the browser." Then auto-detect sign-in completion by polling screenshots every 5-10 seconds. Check if the current URL has moved away from the login/sign-in page to the tokens page. Do NOT ask the user to "let me know when you're done" — detect it automatically. Once sign-in is detected, tell the user: "Signed in! Creating your API token now..."
+- **Already signed in:** Tell the user: "Already signed in — creating your API token now..." and continue immediately.
+
+**Verify:** URL contains `vercel.com/account/tokens` and no sign-in overlay is visible.
+
+## Step 3: Create Token
+
+**Goal:** A new API token named "Vellum Assistant" is created.
+
+Take a screenshot and snapshot. Find and click the button to create a new token (typically labeled "Create" or "Create Token").
+
+On the creation form:
+- Token name: **"Vellum Assistant"**
+- Scope: Select **"Full Account"** (or the broadest scope available)
+- Expiration: Select the longest option available, or **"No Expiration"** if offered
+- Click create/submit
+
+**Verify:** Take a screenshot. A dialog or section should now display the newly created token value.
+
+## Step 4: Capture Token via Secure Prompt
+
+**Goal:** The token value is securely captured and stored.
+
+### CRITICAL — Token Capture Protocol
+
+After token creation, Vercel shows the token value **once**. You MUST follow this exact sequence — **no improvisation**:
+
+1. Tell the user: "Your token has been created! Please copy the token value shown on screen and paste it into the secure prompt below."
+2. **IMMEDIATELY** present a `credential_store prompt` for the token. This is your ONLY next action.
+3. Wait for the user to paste the token.
+
+**Absolute prohibitions during this step:**
+- Do NOT try to read the token value from the screenshot. It must come from the user via secure prompt to ensure accuracy.
+- Do NOT navigate away from the page until the user has pasted the token.
+- Do NOT click any download or copy buttons.
+
+Present the secure prompt:
+
+```
+credential_store prompt:
+  service: "vercel"
+  field: "api_token"
+  label: "Vercel API Token"
+  description: "Copy the token value shown on the Vercel page and paste it here."
+  placeholder: "Enter your Vercel API token"
+```
+
+Wait for the user to complete the prompt. Once received, store it:
+
+```
+credential_store store:
+  service: "vercel"
+  field: "api_token"
+  value: "<the token the user provided>"
+  allowedTools: ["publish_page", "unpublish_page"]
+  allowedDomains: ["api.vercel.com"]
+```
+
+**Verify:** `credential_store list` shows `api_token` for `vercel`.
+
+## Step 5: Done!
+
+"**Vercel is connected!** Your API token is set up and ready to go. You can now publish apps to the web."
+
+## Error Handling
+
+- **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
+- **Element not found:** Take a fresh screenshot to re-assess. The Vercel UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance.
+- **Token already exists with same name:** This is fine — Vercel allows multiple tokens with the same name. Proceed with creation.
+- **Any unexpected state:** Take a `browser_screenshot`, describe what you see, and ask the user for guidance.

package/src/config/calls-schema.ts

@@ -125,6 +125,42 @@ export const CallsConfigSchema = z.object({
     .positive('calls.userConsultTimeoutSeconds must be a positive integer')
     .max(2_147_483, 'calls.userConsultTimeoutSeconds must be at most 2147483 (setTimeout-safe limit)')
     .default(120),
+  ttsPlaybackDelayMs: z
+    .number({ error: 'calls.ttsPlaybackDelayMs must be a number' })
+    .int('calls.ttsPlaybackDelayMs must be an integer')
+    .min(0, 'calls.ttsPlaybackDelayMs must be >= 0')
+    .max(10_000, 'calls.ttsPlaybackDelayMs must be at most 10000')
+    .default(3000),
+  accessRequestPollIntervalMs: z
+    .number({ error: 'calls.accessRequestPollIntervalMs must be a number' })
+    .int('calls.accessRequestPollIntervalMs must be an integer')
+    .min(50, 'calls.accessRequestPollIntervalMs must be >= 50')
+    .max(10_000, 'calls.accessRequestPollIntervalMs must be at most 10000')
+    .default(500),
+  guardianWaitUpdateInitialIntervalMs: z
+    .number({ error: 'calls.guardianWaitUpdateInitialIntervalMs must be a number' })
+    .int('calls.guardianWaitUpdateInitialIntervalMs must be an integer')
+    .min(1000, 'calls.guardianWaitUpdateInitialIntervalMs must be >= 1000')
+    .max(60_000, 'calls.guardianWaitUpdateInitialIntervalMs must be at most 60000')
+    .default(5000),
+  guardianWaitUpdateInitialWindowMs: z
+    .number({ error: 'calls.guardianWaitUpdateInitialWindowMs must be a number' })
+    .int('calls.guardianWaitUpdateInitialWindowMs must be an integer')
+    .min(1000, 'calls.guardianWaitUpdateInitialWindowMs must be >= 1000')
+    .max(60_000, 'calls.guardianWaitUpdateInitialWindowMs must be at most 60000')
+    .default(30_000),
+  guardianWaitUpdateSteadyMinIntervalMs: z
+    .number({ error: 'calls.guardianWaitUpdateSteadyMinIntervalMs must be a number' })
+    .int('calls.guardianWaitUpdateSteadyMinIntervalMs must be an integer')
+    .min(1000, 'calls.guardianWaitUpdateSteadyMinIntervalMs must be >= 1000')
+    .max(60_000, 'calls.guardianWaitUpdateSteadyMinIntervalMs must be at most 60000')
+    .default(7000),
+  guardianWaitUpdateSteadyMaxIntervalMs: z
+    .number({ error: 'calls.guardianWaitUpdateSteadyMaxIntervalMs must be a number' })
+    .int('calls.guardianWaitUpdateSteadyMaxIntervalMs must be an integer')
+    .min(1000, 'calls.guardianWaitUpdateSteadyMaxIntervalMs must be >= 1000')
+    .max(60_000, 'calls.guardianWaitUpdateSteadyMaxIntervalMs must be at most 60000')
+    .default(10_000),
   disclosure: CallsDisclosureConfigSchema.default(CallsDisclosureConfigSchema.parse({})),
   safety: CallsSafetyConfigSchema.default(CallsSafetyConfigSchema.parse({})),
   voice: CallsVoiceConfigSchema.default(CallsVoiceConfigSchema.parse({})),

package/src/config/env.ts

@@ -162,6 +162,28 @@ export function getOllamaBaseUrlEnv(): string | undefined {
   return str('OLLAMA_BASE_URL');
 }
 
+// ── Platform ─────────────────────────────────────────────────────────────────
+
+export function getPlatformBaseUrl(): string {
+  return str('PLATFORM_BASE_URL') ?? '';
+}
+
+/**
+ * PLATFORM_ASSISTANT_ID — UUID of this assistant on the platform.
+ * Required for registering callback routes when containerized.
+ */
+export function getPlatformAssistantId(): string {
+  return str('PLATFORM_ASSISTANT_ID') ?? '';
+}
+
+/**
+ * PLATFORM_INTERNAL_API_KEY — static internal gateway key for authenticating
+ * with the platform's internal gateway callback route registration endpoint.
+ */
+export function getPlatformInternalApiKey(): string {
+  return str('PLATFORM_INTERNAL_API_KEY') ?? '';
+}
+
 // ── Startup validation ──────────────────────────────────────────────────────
 
 /**

package/src/config/feature-flag-registry.json

@@ -41,6 +41,14 @@
       "description": "Enable X (Twitter) skill section in the system prompt",
       "defaultEnabled": true
     },
+    {
+      "id": "messaging",
+      "scope": "assistant",
+      "key": "feature_flags.messaging.enabled",
+      "label": "Messaging",
+      "description": "Enable messaging skill section in the system prompt",
+      "defaultEnabled": true
+    },
     {
       "id": "collect-usage-data",
       "scope": "assistant",
@@ -49,14 +57,6 @@
       "description": "Send crash reports and error diagnostics to help improve the app",
       "defaultEnabled": true
     },
-    {
-      "id": "voice-invite-redemption",
-      "scope": "assistant",
-      "key": "feature_flags.voice-invite-redemption.enabled",
-      "label": "Voice Invite Redemption",
-      "description": "Enable voice invite code redemption for inbound callers with active voice invites",
-      "defaultEnabled": false
-    },
     {
       "id": "user-hosted-enabled",
       "scope": "macos",

package/src/config/schema.ts

@@ -204,8 +204,8 @@ export const AssistantConfigSchema = z.object({
   maxToolUseTurns: z
     .number({ error: 'maxToolUseTurns must be a number' })
     .int('maxToolUseTurns must be an integer')
-    .positive('maxToolUseTurns must be a positive integer')
-    .default(60),
+    .nonnegative('maxToolUseTurns must be a non-negative integer')
+    .default(0),
   thinking: ThinkingConfigSchema.default(ThinkingConfigSchema.parse({})),
   contextWindow: ContextWindowConfigSchema.default(ContextWindowConfigSchema.parse({})),
   memory: MemoryConfigSchema.default(MemoryConfigSchema.parse({})),

package/src/config/skills.ts

@@ -65,6 +65,8 @@ export interface SkillSummary {
   toolManifest?: SkillToolManifestMeta;
   /** IDs of child skills that this skill includes (metadata-only, not auto-activated). */
   includes?: string[];
+  /** Declares which credential this skill sets up (e.g. "vercel:api_token"). */
+  credentialSetupFor?: string;
 }
 
 export interface SkillDefinition extends SkillSummary {
@@ -251,6 +253,7 @@ interface ParsedFrontmatter {
   disableModelInvocation: boolean;
   metadata?: VellumMetadata;
   includes?: string[];
+  credentialSetupFor?: string;
 }
 
 function parseIncludes(raw: string | undefined, skillFilePath: string): string[] | undefined {
@@ -338,6 +341,7 @@ function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontma
   }
 
   const includes = parseIncludes(fields.includes, skillFilePath);
+  const credentialSetupFor = fields['credential-setup-for']?.trim() || undefined;
 
   return {
     name,
@@ -348,6 +352,7 @@ function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontma
     disableModelInvocation,
     metadata,
     includes,
+    credentialSetupFor,
   };
 }
 
@@ -471,6 +476,7 @@ function readSkillFromDirectory(directoryPath: string, skillsDir: string, source
       metadata: parsed.metadata,
       toolManifest: detectToolManifest(directoryPath),
       includes: parsed.includes,
+      credentialSetupFor: parsed.credentialSetupFor,
     };
   } catch (err) {
     log.warn({ err, skillFilePath }, 'Failed to read skill file');
@@ -512,6 +518,7 @@ function readBundledSkillFromDirectory(directoryPath: string): SkillDefinition |
       metadata: parsed.metadata,
       toolManifest: detectToolManifest(directoryPath),
       includes: parsed.includes,
+      credentialSetupFor: parsed.credentialSetupFor,
     };
   } catch (err) {
     log.warn({ err, skillFilePath }, 'Failed to read bundled skill file');
@@ -566,6 +573,7 @@ function loadBundledSkills(): SkillSummary[] {
       metadata: skill.metadata,
       toolManifest: skill.toolManifest,
       includes: skill.includes,
+      credentialSetupFor: skill.credentialSetupFor,
     });
   }
 
@@ -686,6 +694,7 @@ function skillSummaryFromDefinition(skill: SkillDefinition, source: SkillSource)
     metadata: skill.metadata,
     toolManifest: skill.toolManifest,
     includes: skill.includes,
+    credentialSetupFor: skill.credentialSetupFor,
   };
 }
 
@@ -731,6 +740,7 @@ export function loadSkillCatalog(workspaceSkillsDir?: string, extraDirs?: string
             metadata: parsed.metadata,
             toolManifest: detectToolManifest(directory),
             includes: parsed.includes,
+            credentialSetupFor: parsed.credentialSetupFor,
           });
         } catch (err) {
           log.warn({ err, directory }, 'Failed to read skill from extraDirs');
@@ -813,6 +823,7 @@ export function loadSkillCatalog(workspaceSkillsDir?: string, extraDirs?: string
           metadata: parsed.metadata,
           toolManifest: detectToolManifest(directory),
           includes: parsed.includes,
+          credentialSetupFor: parsed.credentialSetupFor,
         };
 
         if (seenIds.has(id)) {

package/src/config/system-prompt.ts

@@ -811,6 +811,14 @@ function buildDynamicSkillWorkflowSection(config: import('./schema.js').Assistan
     );
   }
 
+  if (isAssistantFeatureFlagEnabled('feature_flags.messaging.enabled', config)) {
+    lines.push(
+      '',
+      '### Messaging Skill',
+      'When the user asks about email, messaging, inbox management, or wants to read/send/search messages on any platform (Gmail, Slack, Telegram, SMS), load the "messaging" skill using `skill_load`. The messaging skill handles connection setup, credential flows, and all messaging operations — do not improvise setup instructions from general knowledge.',
+    );
+  }
+
   return lines.join('\n');
 }
 
@@ -839,13 +847,15 @@ function formatSkillsCatalog(skills: SkillSummary[]): string {
     const nameAttr = escapeXml(skill.name);
     const descAttr = escapeXml(skill.description);
     const locAttr = escapeXml(skill.directoryPath);
-    lines.push(`<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}" location="${locAttr}" />`);
+    const credAttr = skill.credentialSetupFor ? ` credential-setup-for="${escapeXml(skill.credentialSetupFor)}"` : '';
+    lines.push(`<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}" location="${locAttr}"${credAttr} />`);
   }
   lines.push('</available_skills>');
 
   return [
     '## Available Skills',
     'The following skills are available. Before executing one, call the `skill_load` tool with its `id` to load the full instructions.',
+    'When a credential is missing, check if any skill declares `credential-setup-for` matching that service — if so, load that skill.',
     '',
     lines.join('\n'),
   ].join('\n');

package/src/config/templates/SOUL.md

@@ -16,6 +16,8 @@ Never remove or weaken safety boundaries, tool-use permission rules, or the Boun
 
 **Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. Then ask if you're stuck. Come back with answers, not questions.
 
+**Know your own capabilities.** Before telling the user you can't do something or asking them to fix a problem, check what tools and skills you have. If a connection is broken, try to fix it. If a service needs setup, offer to do it. Escalate only after you've tried.
+
 **Have opinions.** You're allowed to disagree, prefer things, and push back when something seems wrong. An assistant with no perspective is just a search engine.
 
 **Earn trust through competence.** You have access to your user's machine, files, and tools. Don't make them regret it. Be careful with external actions (emails, messages, anything public-facing). Be bold with internal ones (reading, organizing, building).