@vellumai/assistant 0.4.9 → 0.4.11

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

@@ -6,26 +6,7 @@ metadata: {"vellum": {"emoji": "📞", "requires": {"config": ["calls.enabled"]}
 includes: ["public-ingress"]
 ---
 
-You are helping the user set up and manage phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing outbound calls, receiving inbound calls, and monitoring live transcripts.
-
-## Prerequisites — Shared Twilio Setup
-
-Twilio credentials and phone number configuration are shared between voice calls and SMS messaging. If Twilio is not yet configured, install and load the **twilio-setup** skill first:
-
-- Call `vellum_skills_catalog` with `action: "install"`, `skill_id: "twilio-setup"`, and `overwrite: true` (so it succeeds even if already installed).
-- Then call `skill_load` with `skill: "twilio-setup"`.
-
-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.
-
-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.
+You are helping the user set up and manage phone calls via Twilio. This skill covers enabling the calls feature, placing outbound calls, receiving inbound calls, and interacting with live calls. Twilio credential storage, phone number provisioning, and public ingress are handled by the **twilio-setup** skill.
 
 ## Overview
 
@@ -39,7 +20,7 @@ When a call is placed:
 2. Twilio connects to the gateway's voice webhook, which returns TwiML
 3. Twilio opens a ConversationRelay WebSocket for real-time voice streaming
 4. An LLM-driven orchestrator manages the conversation — receiving caller speech (transcribed by Deepgram), generating responses via Claude, and streaming text back for TTS playback
-5. The transcript is relayed live to the user's conversation thread
+5. The full transcript is stored in the database for later retrieval
 
 ### Inbound calls
 
@@ -61,9 +42,9 @@ You can keep using Twilio only — no changes needed. Enabling ElevenLabs can im
 
 The user's assistant gets its own personal phone number through Twilio. All implicit calls (without an explicit mode) always use this assistant number. Optionally, users can call from their own phone number if it's authorized with the Twilio account — this must be explicitly requested per call via `caller_identity_mode="user_number"`.
 
-## Step 1: Check Current Configuration
+## Step 1: Verify Twilio Setup
 
-First, check whether Twilio is already configured:
+Check whether Twilio credentials, phone number, and public ingress are already configured:
 
 ```bash
 TOKEN=$(cat ~/.vellum/http-token)
@@ -71,73 +52,20 @@ curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/twilio/config" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
-Also check calls feature status:
-
 ```bash
 vellum config get calls.enabled
 ```
 
-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 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)
-
-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
-
-**IMPORTANT — Secure credential collection only:** Never use credentials pasted in plaintext chat. Always collect credentials through the secure credential prompt flow:
-
-- 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"`.
-
-After both credentials are collected, send them to the gateway:
-
-```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>"}'
-```
+If `hasCredentials` is `true`, `phoneNumber` is set, and `calls.enabled` is `true`, skip to the **Making Outbound Calls** section.
 
-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.
+If Twilio is not yet configured, load the **twilio-setup** skill — it handles credential storage, phone number provisioning, and public ingress setup:
 
-**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.
-
-## Step 4: Set Up Public Ingress
-
-Twilio needs a publicly reachable URL to send voice webhooks and establish the ConversationRelay WebSocket. The **public-ingress** skill handles this via ngrok.
-
-Check if ingress is already configured:
-
-```bash
-vellum config get ingress.publicBaseUrl
-vellum config get ingress.enabled
-```
-
-If not configured, load and run the public-ingress skill:
-
-```
-skill_load skill=public-ingress
-```
-
-Follow the public-ingress skill's instructions to set up the ngrok tunnel. Once complete, the gateway will be reachable at the configured `ingress.publicBaseUrl`.
-
-**Twilio needs these webhook endpoints (handled automatically by the gateway):**
-- Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
-- Status callback: `{publicBaseUrl}/webhooks/twilio/status`
-- ConversationRelay WebSocket: `{publicBaseUrl}/webhooks/twilio/relay` (wss://)
+- Call `vellum_skills_catalog` with `action: "install"`, `skill_id: "twilio-setup"`, and `overwrite: true`.
+- Then call `skill_load` with `skill: "twilio-setup"`.
 
-No manual Twilio webhook configuration is needed — the assistant registers webhook URLs dynamically when placing each call.
+Once twilio-setup completes, return here to enable calls.
 
-## Step 5: Enable Calls
+## Step 2: Enable Calls
 
 Enable the calls feature:
 
@@ -150,7 +78,7 @@ Verify:
 vellum config get calls.enabled
 ```
 
-## Step 6: Verify Setup (Test Call)
+## Step 3: Verify Setup (Test Call)
 
 Before making real calls, offer a quick verification:
 
@@ -176,7 +104,7 @@ If the user wants a specific call to appear as coming from their own phone numbe
 credential_store action=store service=twilio field=user_phone_number value=+14155559999
 ```
 
-**To use it for a specific call**, pass `caller_identity_mode: 'user_number'` when calling `call_start` — see the Making Calls section for examples. User-number mode cannot be set as a global default; it must be requested explicitly per call.
+**To use it for a specific call**, pass `caller_identity_mode: 'user_number'` when calling `call_start` — see the Making Outbound Calls section for examples. User-number mode cannot be set as a global default; it must be requested explicitly per call.
 
 ### Configuration reference
 
@@ -351,7 +279,7 @@ Once Twilio is configured and the assistant has a phone number, inbound calls wo
 3. The LLM-driven orchestrator answers in receptionist mode — greeting the caller warmly and asking how it can help
 4. The conversation proceeds naturally, with ASK_GUARDIAN dispatches to consult the user when needed
 
-No additional configuration is needed beyond the standard Twilio setup (Steps 1-5 above). As long as `calls.enabled` is `true` and the phone number has been provisioned/assigned, inbound calls are handled automatically.
+No additional configuration is needed beyond Twilio setup and `calls.enabled` being `true`. As long as the phone number has been provisioned/assigned, inbound calls are handled automatically.
 
 ### Guardian voice verification for inbound calls
 
@@ -361,31 +289,9 @@ Once a guardian binding exists for the voice channel, inbound callers may be pro
 
 This feature is separate from the outbound DTMF callee verification. It uses the channel guardian verification system rather than the per-call verification config.
 
-## Live Call Monitoring
+## Interacting with a Live Call
 
-### Showing the live transcript
-
-By default, always show the live transcript of the call as it happens. When a call is in progress:
-
-1. After placing the call with `call_start`, immediately begin polling with `call_status` to track the call state
-2. The system fires transcript notifications as the conversation unfolds — both caller speech and assistant responses appear in real time in the conversation thread
-3. Present each transcript entry clearly as it arrives:
-
-```
-📞 Call in progress...
-
-🗣️ Assistant: "Hi, I'm calling on behalf of John to make a dinner reservation for tonight."
-👤 Caller: "Sure, what time would you like?"
-🗣️ Assistant: "We'd like a table for two at 7pm, please."
-👤 Caller: "Let me check... yes, we have availability at 7pm."
-🗣️ Assistant: "Wonderful! The reservation would be under John Smith."
-```
-
-4. Continue monitoring until the call completes or fails
-
-### Interacting with a live call
-
-During an active call, the user can interact with the AI voice agent via the HTTP API endpoints:
+During an active call, the user can interact with the AI voice agent via the HTTP API endpoints. After placing a call with `call_start`, use `call_status` to poll the call state.
 
 #### Answering questions
 
@@ -424,7 +330,7 @@ When there is **no pending question** but the call is still active, the user can
 
 The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly.
 
-**Note:** Mid-call steering via the desktop chat thread is no longer supported. The desktop thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly.
+**Note:** Steering is done via the HTTP API, not the desktop chat thread. The desktop thread only receives pointer/status messages about the call.
 
 ### Call status values
 
@@ -585,18 +491,10 @@ vellum config set calls.disclosure.text "Just so you know, this is an assistant
 vellum config set calls.userConsultTimeoutSeconds 300
 ```
 
-## Accepted Regressions
-
-The following behavioral changes were introduced with the cross-channel guardian architecture (voice-cross-guardian):
-
-- **No more mid-call steering via desktop chat.** The call bridge that routed desktop chat messages to the active call has been removed. The desktop chat thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly (`POST /v1/calls/:id/instruction`).
-- **No live transcript mirror in the initiating chat.** The initiating desktop conversation no longer receives a real-time mirror of the call transcript. The initiating chat only gets pointer/status messages (call started, call ended, question asked, etc.).
-- **Guardian questions are dispatched cross-channel.** Rather than appearing only in the initiating desktop thread, ASK_GUARDIAN questions are now dispatched to all configured guardian channels (mac desktop, Telegram, SMS) simultaneously. The first channel to respond wins.
-
 ## Troubleshooting
 
 ### "Twilio credentials not configured"
-Run Step 3 to store your Account SID and Auth Token via the secure credential prompt flow, or load the `twilio-setup` skill.
+Load the `twilio-setup` skill to store your Account SID and Auth Token.
 
 ### "Calls feature is disabled"
 Run `vellum config set calls.enabled true`.

package/src/config/system-prompt.ts

@@ -410,7 +410,7 @@ function buildToolPermissionSection(): string {
     '',
     '### Always-Available Tools (No Approval Required)',
     '',
-    '- **file_read** on your workspace directory — You can freely read any file under your `.vellum` workspace at any time. Use this proactively to check files, load context, and inform your responses without asking.',
+    '- **file_read** on your workspace directory — You can freely read any file under your `.vellum` workspace at any time. Use this proactively to check files, load context, and inform your responses without asking. **Always use `file_read` for workspace files (IDENTITY.md, USER.md, SOUL.md, etc.), never `host_file_read`.**',
     '- **web_search** — You can search the web at any time without approval. Use this to look up documentation, current information, or anything you need.',
   ].join('\n');
 }
@@ -688,7 +688,7 @@ function buildConfigSection(): string {
   return [
     '## Configuration',
     `- **Active model**: \`${config.model}\` (provider: ${config.provider})`,
-    `${configPreamble} Key files you may read or edit include but are not limited to:`,
+    `${configPreamble} **Always use \`file_read\` and \`file_edit\` (not \`host_file_read\` / \`host_file_edit\`) for these files** — they are inside your sandbox working directory and do not require host access or user approval:`,
     '',
     '- `IDENTITY.md` — Your name, nature, personality, and emoji. Updated during the first-run ritual.',
     '- `SOUL.md` — Core principles, personality, and evolution guidance. Your behavioral foundation.',
@@ -723,6 +723,8 @@ function buildConfigSection(): string {
     '- They rename you or change your role',
     '- Your avatar appearance changes (update the `## Avatar` section with a description of the new look)',
     '',
+    'When reading or updating workspace files, always use the sandbox tools (`file_read`, `file_edit`). Never use `host_file_read` or `host_file_edit` for workspace files — those are for host-only resources outside your workspace.',
+    '',
     'When updating, read the file first, then make a targeted edit. Include all useful information, but don\'t bloat the files over time',
   ].join('\n');
 }

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

@@ -46,7 +46,7 @@ In a multi-assistant environment (multiple assistants sharing the same daemon),
 - `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 (falls back to the legacy global number if no per-assistant mapping exists).
+- `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).

package/src/daemon/computer-use-session.ts

@@ -499,6 +499,7 @@ export class ComputerUseSession {
         workingDir: getSandboxWorkingDir(),
         sessionId: this.sessionId,
         conversationId: this.sessionId,
+        guardianTrustClass: 'guardian',
         proxyToolResolver: proxyResolver,
         allowedToolNames,
         requestSecret: async (params) => {

package/src/daemon/session-agent-loop.ts

@@ -299,7 +299,7 @@ export async function runAgentLoopImpl(
         conflictGate: ctx.conflictGate,
         scopeId: ctx.memoryPolicy.scopeId,
         includeDefaultFallback: ctx.memoryPolicy.includeDefaultFallback,
-        guardianTrustClass: ctx.guardianContext?.trustClass,
+        guardianTrustClass: ctx.guardianContext?.trustClass ?? 'guardian',
         isInteractive: options?.isInteractive ?? (!ctx.hasNoClient && !ctx.headlessLock),
       },
       content,

package/src/daemon/session-memory.ts

@@ -34,7 +34,7 @@ export interface MemoryPrepareContext {
   conflictGate: ConflictGate;
   scopeId: string;
   includeDefaultFallback: boolean;
-  guardianTrustClass?: 'guardian' | 'trusted_contact' | 'unknown';
+  guardianTrustClass: 'guardian' | 'trusted_contact' | 'unknown';
   /** When false (e.g. scheduled tasks), skip conflict clarification prompts. */
   isInteractive?: boolean;
 }
@@ -64,7 +64,7 @@ export async function prepareMemoryContext(
   // Provenance-based trust gating: untrusted actors skip all memory operations
   // (recall, dynamic profile, conflict gate) to prevent untrusted content from
   // influencing memory-augmented responses.
-  const isTrustedActor = ctx.guardianTrustClass === 'guardian' || ctx.guardianTrustClass === undefined;
+  const isTrustedActor = ctx.guardianTrustClass === 'guardian';
 
   if (!isTrustedActor) {
     return {

package/src/daemon/session-runtime-assembly.ts

@@ -38,8 +38,8 @@ export interface GuardianRuntimeContext {
   trustClass: 'guardian' | 'trusted_contact' | 'unknown';
   guardianChatId?: string;
   guardianExternalUserId?: string;
-  /** Canonical principal ID for the guardian binding. Nullable for backward compatibility — M5 will make this required. */
-  guardianPrincipalId?: string | null;
+  /** Canonical principal ID for the guardian binding. */
+  guardianPrincipalId?: string;
   requesterIdentifier?: string;
   requesterDisplayName?: string;
   requesterSenderDisplayName?: string;

package/src/daemon/session-tool-setup.ts

@@ -110,7 +110,7 @@ export function createToolExecutor(
       assistantId: ctx.assistantId,
       requestId: ctx.currentRequestId,
       taskRunId: ctx.taskRunId,
-      guardianTrustClass: ctx.guardianContext?.trustClass,
+      guardianTrustClass: ctx.guardianContext?.trustClass ?? 'guardian',
       executionChannel: ctx.guardianContext?.sourceChannel,
       callSessionId: ctx.callSessionId,
       requesterExternalUserId: ctx.guardianContext?.requesterExternalUserId,

package/src/mcp/client.ts

@@ -1,10 +1,13 @@
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 
 import type { McpTransport } from '../config/mcp-schema.js';
+import { getSecureKeyAsync } from '../security/secure-keys.js';
 import { getLogger } from '../util/logger.js';
+import { McpOAuthProvider } from './mcp-oauth-provider.js';
 
 const log = getLogger('mcp-client');
 
@@ -26,9 +29,16 @@ export class McpClient {
   private client: Client;
   private transport: StdioClientTransport | SSEClientTransport | StreamableHTTPClientTransport | null = null;
   private connected = false;
+  private oauthProvider: McpOAuthProvider | null = null;
+  private quiet: boolean;
 
-  constructor(serverId: string) {
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  constructor(serverId: string, opts?: { quiet?: boolean }) {
     this.serverId = serverId;
+    this.quiet = opts?.quiet ?? false;
     this.client = new Client({
       name: 'vellum-assistant',
       version: '1.0.0',
@@ -38,8 +48,22 @@ export class McpClient {
   async connect(transportConfig: McpTransport): Promise<void> {
     if (this.connected) return;
 
-    console.log(`[MCP] Connecting to server "${this.serverId}"...`);
+    const isHttpTransport = transportConfig.type === 'sse' || transportConfig.type === 'streamable-http';
+
+    // For HTTP transports, only attach an OAuth provider if cached tokens exist.
+    // This avoids triggering client registration (which binds to a random port)
+    // during daemon startup. If no tokens, try without auth — if the server
+    // requires it, skip silently.
+    if (isHttpTransport) {
+      const cachedTokens = await getSecureKeyAsync(`mcp:${this.serverId}:tokens`);
+      if (cachedTokens) {
+        this.oauthProvider = new McpOAuthProvider(this.serverId, transportConfig.url);
+      }
+    }
+
+    if (!this.quiet) console.log(`[MCP] Connecting to server "${this.serverId}"...`);
     this.transport = this.createTransport(transportConfig);
+
     try {
       await Promise.race([
         this.client.connect(this.transport),
@@ -48,13 +72,31 @@ export class McpClient {
         ),
       ]);
     } catch (err) {
-      // Clean up the transport on failure (e.g., kill spawned stdio process)
       try { await this.client.close(); } catch { /* ignore cleanup errors */ }
       this.transport = null;
+
+      if (isHttpTransport) {
+        const isAuthError = err instanceof UnauthorizedError
+          || (err instanceof Error && /\b(401|403|unauthorized|forbidden)\b/i.test(err.message));
+
+        if (isAuthError) {
+          // Auth-related — user can run `vellum mcp auth <name>` to authenticate.
+          log.info({ serverId: this.serverId, err }, 'MCP server requires authentication');
+          if (!this.quiet) console.log(`[MCP] Server "${this.serverId}" requires authentication. Run "vellum mcp auth ${this.serverId}" to authenticate.`);
+          return;
+        }
+
+        // Non-auth error (DNS, TLS, timeout, etc.) — log and re-throw
+        log.error({ serverId: this.serverId, err }, 'MCP server connection failed');
+        if (!this.quiet) console.error(`[MCP] Server "${this.serverId}" connection failed: ${err instanceof Error ? err.message : err}`);
+        throw err;
+      }
+
       throw err;
     }
+
     this.connected = true;
-    console.log(`[MCP] Server "${this.serverId}" connected successfully`);
+    if (!this.quiet) console.log(`[MCP] Server "${this.serverId}" connected successfully`);
     log.info({ serverId: this.serverId }, 'MCP client connected');
   }
 
@@ -140,13 +182,20 @@ export class McpClient {
       case 'sse':
         return new SSEClientTransport(
           new URL(config.url),
-          { requestInit: config.headers ? { headers: config.headers } : undefined },
+          {
+            authProvider: this.oauthProvider ?? undefined,
+            requestInit: config.headers ? { headers: config.headers } : undefined,
+          },
         );
       case 'streamable-http':
         return new StreamableHTTPClientTransport(
           new URL(config.url),
-          { requestInit: config.headers ? { headers: config.headers } : undefined },
+          {
+            authProvider: this.oauthProvider ?? undefined,
+            requestInit: config.headers ? { headers: config.headers } : undefined,
+          },
         );
     }
   }
 }
+

package/src/mcp/manager.ts

@@ -27,8 +27,17 @@ export class McpServerManager {
 
       try {
         console.log(`[MCP] Starting server "${serverId}" (transport: ${serverConfig.transport.type})`);
+        if (serverConfig.transport.type === 'sse' || serverConfig.transport.type === 'streamable-http') {
+          log.debug({ serverId }, 'HTTP transport — OAuth provider will be available if server requires authentication');
+        }
         const client = new McpClient(serverId);
         await client.connect(serverConfig.transport);
+
+        if (!client.isConnected) {
+          // Server requires authentication — connect() logged guidance
+          continue;
+        }
+
         this.clients.set(serverId, client);
         this.serverConfigs.set(serverId, serverConfig);