@vellumai/assistant 0.4.3 → 0.4.4

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

@@ -7,6 +7,21 @@ metadata: {"vellum": {"emoji": "💬"}}
 
 You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
 
+## Email Routing Priority
+
+When the user mentions "email" — sending, reading, checking, decluttering, drafting, or anything else — **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
+
+Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup — do not suggest AgentMail as an alternative.
+
+## Communication Style
+
+- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox — that's obviously what they want.
+- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Gmail needs to be reconnected" — not "the OAuth2 access token for integration:gmail has expired."
+- **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
+- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do — just do it and narrate lightly.
+
+When a platform is connected (auth test succeeds), always use the messaging API tools for that platform. Never fall back to browser automation, shell commands (bash, curl), or any other approach for operations that messaging tools can handle. The messaging tools handle authentication internally — never try to access tokens or call APIs directly. Browser automation is only appropriate for initial credential setup (OAuth consent screens), not for day-to-day messaging operations.
+
 ## Connection Setup
 
 Before using any messaging tool, verify that the platform is connected by calling `messaging_auth_test` with the appropriate `platform` parameter. If the call fails with a token/authorization error, follow the steps below.
@@ -15,6 +30,14 @@ Before using any messaging tool, verify that the platform is connected by callin
 
 Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth callbacks or webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Each setup skill below declares `public-ingress` as a dependency and will prompt you to run it if `ingress.publicBaseUrl` is not configured.
 
+### Email Connection Flow
+
+When the user asks to "connect my email", "set up email", "manage my email", or similar — and has not named a specific provider:
+
+1. **Discover what's connected.** Call `messaging_auth_test` for `gmail` (and any other email-capable platforms). If one succeeds, tell the user it's already connected and proceed with their request.
+2. **If nothing is connected**, ask which provider they use — but keep it brief and conversational (e.g., "Which email do you use — Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
+3. **Once the provider is known, act immediately.** Don't present setup options or explain OAuth. If it's Gmail, follow the Gmail section below. For any other provider, let the user know that only Gmail is fully supported right now, and offer to set up Gmail instead.
+
 ### Gmail
 1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials — so this single call may be all that's needed.
 2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Install and load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
@@ -70,12 +93,21 @@ If the user asks to verify their guardian identity for any channel (SMS, voice,
 
 The guardian-verify-setup skill handles the full outbound verification flow for all supported channels. It collects the user's destination (phone number or Telegram chat ID/handle), initiates an outbound verification session, and guides the user through entering or replying with the verification code. This is the single source of truth for guardian verification setup -- do not duplicate the verification flow inline.
 
+## Error Recovery
+
+When a messaging tool fails with a token or authorization error:
+
+1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and the appropriate `service`. This often resolves expired tokens automatically.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected — let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-setup** for Gmail). The user came to you to get something done, not to troubleshoot OAuth — make it seamless.
+3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the messaging tools can't do it, the reconnection flow is the answer.
+4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
+
 ## Platform Selection
 
 - If the user specifies a platform (e.g., "check my Slack"), pass it as the `platform` parameter.
 - If only one platform is connected, it is auto-selected.
 - If multiple platforms are connected and the user doesn't specify, ask which platform they mean — or search across all of them.
-- **Do not assume a specific provider.** When the user says "email" or "manage my email" without naming a provider, call `messaging_auth_test` for each email-capable platform to discover what's connected — don't default to Gmail or any other specific provider. Present whatever is connected; if nothing is, ask the user which email service they use and offer to set it up.
+- **Be action-oriented with email.** When the user says "email" and wants to *do* something (declutter, check, search, send), check what's connected first. If nothing is connected, ask which provider briefly and then go straight into setup — don't present menus, options lists, or explain the setup process. Just do it.
 
 ## Capabilities
 
@@ -217,27 +249,44 @@ Medium and high risk tools require a confidence score between 0 and 1:
 
 Use `messaging_analyze_activity` to classify channels or conversations by activity level (high, medium, low, dead). Useful for decluttering — suggest leaving dead channels or archiving old emails.
 
-## Newsletter Decluttering
+## Email Decluttering
+
+When a user asks to declutter, clean up, or organize their email — start scanning immediately. Don't ask what kind of cleanup they want or request permission to read their inbox. Go straight to scanning — but once results are ready, always show them via `ui_show` and let the user choose actions before archiving or unsubscribing.
+
+### Provider Selection
 
-Use `gmail_sender_digest` to help users identify and clean up high-volume senders like newsletters, marketing emails, and automated notifications.
+- **Gmail connected**: Use the Gmail-specific tools (`gmail_sender_digest`, `gmail_archive_by_query`, `gmail_unsubscribe`, `gmail_filters`) — they have richer features like unsubscribe support and filter creation.
+- **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) — they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
+- **Nothing connected**: Ask which email provider they use. If it's Gmail, go straight into the Gmail connection flow. For other providers, let the user know only Gmail is supported right now and offer to set up Gmail instead. Don't present a menu of options or explain what OAuth is.
 
 ### Workflow
 
-1. **Scan**: Call `gmail_sender_digest` (default query targets Gmail's promotions category from the last 90 days)
+1. **Scan**: Call `gmail_sender_digest` (or `messaging_sender_digest` for non-Gmail). Default query targets promotions from the last 90 days.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
-   - Columns: Sender, Email Count, Unsubscribable, Date Range, Sample Subject
-   - Action buttons: "Archive & Unsubscribe" (primary), "Archive Only" (secondary)
-3. **Act on selection**: For each selected sender:
-   - Prefer `gmail_archive_by_query` with the sender's `search_query` — this archives all matching messages in one call, regardless of volume
-   - Alternatively, use `gmail_batch_archive` with the sender's `message_ids` for smaller senders where all IDs are already collected
-   - If the action is "Archive & Unsubscribe" and `has_unsubscribe` is true, call `gmail_unsubscribe` with the sender's `newest_message_id`
-4. **Report**: Summarize results — e.g. "Archived 247 messages from 8 senders. Unsubscribed from 6."
+   - **Gmail columns (exactly 3)**: Sender, Emails Found, Unsub?
+   - **Non-Gmail columns (exactly 2)**: Sender, Emails Found (omit the Unsub? column — unsubscribe is not available)
+   - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
+   - **Caption**: "Showing emails from last 90 days in Promotions" (or adjusted to match the query used)
+   - **Gmail action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
+   - **Non-Gmail action button (exactly 1)**: "Archive Selected" (primary). Do not offer an unsubscribe button — it is Gmail-specific. **NEVER offer Delete, Trash, or any destructive action.**
+3. **Live progress**: After the user clicks an action button:
+   - **Dismiss the table immediately** with `ui_dismiss` — it collapses to a completion chip
+   - **Show a `task_progress` card** with one step per selected sender (e.g., "Archiving TechCrunch (247 emails)"). Update each step from `in_progress` → `completed` as each sender finishes.
+   - When all senders are processed, set the progress card's `status: "completed"`.
+4. **Act on selection**: For each selected sender:
+   - Use `gmail_archive_by_query` (or `messaging_archive_by_sender` for non-Gmail) with the sender's `search_query` — this archives all matching messages in one call, regardless of volume
+   - If Gmail and the action is "Archive & Unsubscribe" and `has_unsubscribe` is true, call `gmail_unsubscribe` with the sender's `newest_message_id`
+5. **Accurate summary**: Use the **actual counts returned by the archive tool**, not the scan counts from the digest. The scan is a sample; the archive is comprehensive. Format: "Cleaned up [total_archived] emails from [sender_count] senders." For Gmail, append: "Unsubscribed from [unsub_count]."
+6. **Ongoing protection offer (Gmail only)**: After reporting results, offer auto-archive filters:
+   - "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"
+   - If yes, call `gmail_filters` with `action: "create"` for each sender with `from` set to the sender's email and `remove_label_ids: ["INBOX"]`.
+   - Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?" If yes, use `schedule_create` to set up a monthly declutter check.
 
 ### Edge Cases
 
 - **Zero results**: Tell the user "No newsletter emails found" and suggest broadening the query (e.g. removing the category filter or extending the date range)
 - **Unsubscribe failures**: Report per-sender success/failure; the existing `gmail_unsubscribe` tool handles edge cases
-- **Large sender counts**: The `has_more` flag indicates a sender had more messages than collected — use `search_query` for follow-up archiving
+- **Large sender counts**: The `has_more` flag indicates a sender had more messages than collected — `gmail_archive_by_query` handles this automatically via its own pagination
 
 ## Batch Operations
 

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

@@ -1017,6 +1017,64 @@
       "executor": "tools/gmail-sender-digest.ts",
       "execution_target": "host"
     },
+    {
+      "name": "messaging_sender_digest",
+      "description": "Scan connected email platform and group messages by sender to identify high-volume senders (e.g. newsletters). Works with any email provider that supports sender digest. Returns top senders sorted by message count with metadata for bulk cleanup.",
+      "category": "messaging",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "platform": {
+            "type": "string",
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected."
+          },
+          "query": {
+            "type": "string",
+            "description": "Search query (default 'category:promotions newer_than:90d')"
+          },
+          "max_messages": {
+            "type": "number",
+            "description": "Maximum messages to scan (default 500, cap 2000)"
+          },
+          "max_senders": {
+            "type": "number",
+            "description": "Maximum senders to return (default 30)"
+          }
+        }
+      },
+      "executor": "tools/messaging-sender-digest.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "messaging_archive_by_sender",
+      "description": "Archive all messages matching a search query on the connected email platform. Paginates through all results and archives in bulk. Works with any email provider that supports archive by query. Include a confidence score (0-1).",
+      "category": "messaging",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "platform": {
+            "type": "string",
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected."
+          },
+          "query": {
+            "type": "string",
+            "description": "Search query (e.g. \"from:marketing@example.com category:promotions newer_than:90d\")"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          }
+        },
+        "required": [
+          "query",
+          "confidence"
+        ]
+      },
+      "executor": "tools/messaging-archive-by-sender.ts",
+      "execution_target": "host"
+    },
     {
       "name": "gmail_outreach_scan",
       "description": "Scan Gmail for cold outreach emails (sales, recruiting, marketing) using LLM classification. Returns top outreach senders with suggested cleanup actions. Read-only \u2014 use gmail_batch_archive and gmail_filters for cleanup.",

package/src/config/bundled-skills/messaging/tools/gmail-sender-digest.ts

@@ -161,7 +161,12 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         sample_subjects: s.sampleSubjects,
       }));
 
-      return ok(JSON.stringify({ senders: result, total_scanned: allMessageIds.length }));
+      return ok(JSON.stringify({
+        senders: result,
+        total_scanned: allMessageIds.length,
+        query_used: query,
+        note: `message_count reflects emails found per sender within the ${allMessageIds.length} messages scanned. The archive tool may find additional messages beyond this sample.`,
+      }));
     });
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));

package/src/config/bundled-skills/messaging/tools/messaging-archive-by-sender.ts

@@ -0,0 +1,35 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { err, ok, resolveProvider, withProviderToken } from './shared.js';
+
+export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  const platform = input.platform as string | undefined;
+  const query = input.query as string;
+
+  if (!query) {
+    return err('query is required.');
+  }
+
+  try {
+    const provider = resolveProvider(platform);
+
+    if (!provider.archiveByQuery) {
+      return err(`The ${provider.displayName} provider does not support archive by query.`);
+    }
+
+    return withProviderToken(provider, async (token) => {
+      const result = await provider.archiveByQuery!(token, query);
+
+      if (result.archived === 0) {
+        return ok('No messages matched the query. Nothing archived.');
+      }
+
+      const summary = `Archived ${result.archived} message(s) matching query: ${query}`;
+      if (result.truncated) {
+        return ok(`${summary}\n\nNote: this operation was capped at 5000 messages. Additional messages matching the query may remain in the inbox. Run the command again to archive more.`);
+      }
+      return ok(summary);
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/messaging/tools/messaging-sender-digest.ts

@@ -0,0 +1,52 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { err, ok, resolveProvider, withProviderToken } from './shared.js';
+
+export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  const platform = input.platform as string | undefined;
+  const query = (input.query as string) ?? 'category:promotions newer_than:90d';
+  const maxMessages = input.max_messages as number | undefined;
+  const maxSenders = input.max_senders as number | undefined;
+
+  try {
+    const provider = resolveProvider(platform);
+
+    if (!provider.senderDigest) {
+      return err(`The ${provider.displayName} provider does not support sender digest scanning.`);
+    }
+
+    return withProviderToken(provider, async (token) => {
+      const result = await provider.senderDigest!(token, query, { maxMessages, maxSenders });
+
+      if (result.senders.length === 0) {
+        return ok(JSON.stringify({
+          senders: [],
+          total_scanned: result.totalScanned,
+          query_used: result.queryUsed,
+          message: 'No emails found matching the query. Try broadening the search (e.g. remove category filter or extend date range).',
+        }));
+      }
+
+      // Map to snake_case output format for LLM consumption
+      const senders = result.senders.map((s) => ({
+        id: s.id,
+        display_name: s.displayName,
+        email: s.email,
+        message_count: s.messageCount,
+        has_unsubscribe: s.hasUnsubscribe,
+        newest_message_id: s.newestMessageId,
+        search_query: s.searchQuery,
+        message_ids: s.messageIds,
+        has_more: s.hasMore,
+      }));
+
+      return ok(JSON.stringify({
+        senders,
+        total_scanned: result.totalScanned,
+        query_used: result.queryUsed,
+        note: `message_count reflects emails found per sender within the ${result.totalScanned} messages scanned. The archive tool may find additional messages beyond this sample.`,
+      }));
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

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

@@ -2,6 +2,7 @@
 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": "▲"}}
 ---
 

package/src/config/calls-schema.ts

@@ -137,6 +137,30 @@ export const CallsConfigSchema = z.object({
     .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",

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)) {