vellum 0.2.9 → 0.2.11

package/src/calls/relay-server.ts

@@ -12,13 +12,16 @@ import {
   getCallSession,
   updateCallSession,
   recordCallEvent,
+  expirePendingQuestions,
 } from './call-store.js';
 import { CallOrchestrator } from './call-orchestrator.js';
+import { fireCallTranscriptNotifier, fireCallCompletionNotifier } from './call-state.js';
 import {
   extractPromptSpeakerMetadata,
   SpeakerIdentityTracker,
   type PromptSpeakerContext,
 } from './speaker-identification.js';
+import { isTerminalState } from './call-state-machine.js';
 
 const log = getLogger('relay-server');
 
@@ -228,6 +231,44 @@ export class RelayConnection {
     log.info({ callSessionId: this.callSessionId }, 'RelayConnection destroyed');
   }
 
+  /**
+   * Handle transport-level close from the relay websocket.
+   *
+   * Twilio status callbacks are best-effort; if they are delayed or absent,
+   * we still finalize the call lifecycle from the relay close signal.
+   */
+  handleTransportClosed(code?: number, reason?: string): void {
+    const session = getCallSession(this.callSessionId);
+    if (!session) return;
+    if (isTerminalState(session.status)) return;
+
+    const isNormalClose = code === 1000;
+    if (isNormalClose) {
+      updateCallSession(this.callSessionId, {
+        status: 'completed',
+        endedAt: Date.now(),
+      });
+      recordCallEvent(this.callSessionId, 'call_ended', {
+        reason: reason || 'relay_closed',
+        closeCode: code,
+      });
+    } else {
+      const detail = reason || (code ? `relay_closed_${code}` : 'relay_closed_abnormal');
+      updateCallSession(this.callSessionId, {
+        status: 'failed',
+        endedAt: Date.now(),
+        lastError: `Relay websocket closed unexpectedly: ${detail}`,
+      });
+      recordCallEvent(this.callSessionId, 'call_failed', {
+        reason: detail,
+        closeCode: code,
+      });
+    }
+
+    expirePendingQuestions(this.callSessionId);
+    fireCallCompletionNotifier(session.conversationId, this.callSessionId);
+  }
+
   // ── Private handlers ─────────────────────────────────────────────
 
   private async handleSetup(msg: RelaySetupMessage): Promise<void> {
@@ -239,7 +280,16 @@ export class RelayConnection {
     // Store the callSid association on the call session
     const session = getCallSession(this.callSessionId);
     if (session) {
-      updateCallSession(this.callSessionId, { providerCallSid: msg.callSid });
+      const updates: Parameters<typeof updateCallSession>[1] = {
+        providerCallSid: msg.callSid,
+      };
+      if (!isTerminalState(session.status) && session.status !== 'in_progress' && session.status !== 'waiting_on_user') {
+        updates.status = 'in_progress';
+        if (!session.startedAt) {
+          updates.startedAt = Date.now();
+        }
+      }
+      updateCallSession(this.callSessionId, updates);
     }
 
     recordCallEvent(this.callSessionId, 'call_connected', {
@@ -286,6 +336,11 @@ export class RelayConnection {
       speakerSource: speaker.source,
     });
 
+    const session = getCallSession(this.callSessionId);
+    if (session) {
+      fireCallTranscriptNotifier(session.conversationId, this.callSessionId, 'caller', msg.voicePrompt);
+    }
+
     // Route to orchestrator for LLM-driven response
     if (this.orchestrator) {
       await this.orchestrator.handleCallerUtterance(msg.voicePrompt, speaker);

package/src/calls/twilio-config.ts

@@ -20,20 +20,16 @@ export function getTwilioConfig(): TwilioConfig {
   const config = loadConfig();
   const webhookBaseUrl = getPublicBaseUrl(config);
 
-  // In gateway_only mode, ignore TWILIO_WSS_BASE_URL and always use the
-  // centralized relay URL derived from the public ingress base URL.
+  // Always use the centralized relay URL derived from the public ingress base URL.
+  // TWILIO_WSS_BASE_URL is ignored.
   let wssBaseUrl: string;
-  if (config.ingress.mode === 'gateway_only') {
-    if (process.env.TWILIO_WSS_BASE_URL) {
-      log.warn('TWILIO_WSS_BASE_URL env var is ignored in gateway-only mode. Relay URL is derived from ingress.publicBaseUrl.');
-    }
-    try {
-      wssBaseUrl = getTwilioRelayUrl(config);
-    } catch {
-      wssBaseUrl = '';
-    }
-  } else {
-    wssBaseUrl = process.env.TWILIO_WSS_BASE_URL || '';
+  if (process.env.TWILIO_WSS_BASE_URL) {
+    log.warn('TWILIO_WSS_BASE_URL env var is ignored. Relay URL is derived from ingress.publicBaseUrl.');
+  }
+  try {
+    wssBaseUrl = getTwilioRelayUrl(config);
+  } catch {
+    wssBaseUrl = '';
   }
 
   if (!accountSid || !authToken) {

package/src/calls/twilio-provider.ts

@@ -45,8 +45,13 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
       To: opts.to,
       Url: opts.webhookUrl,
       StatusCallback: opts.statusCallbackUrl,
-      StatusCallbackEvent: 'initiated ringing answered completed',
     });
+    // Twilio expects repeated StatusCallbackEvent params, not a single
+    // space-delimited string.
+    body.append('StatusCallbackEvent', 'initiated');
+    body.append('StatusCallbackEvent', 'ringing');
+    body.append('StatusCallbackEvent', 'answered');
+    body.append('StatusCallbackEvent', 'completed');
 
     const reservedKeys = new Set(['From', 'To', 'Url', 'StatusCallback', 'StatusCallbackEvent']);
     if (opts.customParams) {

package/src/calls/twilio-routes.ts

@@ -24,6 +24,7 @@ import { isTerminalState } from './call-state-machine.js';
 import { getTwilioConfig } from './twilio-config.js';
 import { loadConfig } from '../config/loader.js';
 import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
+import { fireCallCompletionNotifier } from './call-state.js';
 
 const log = getLogger('twilio-routes');
 
@@ -74,9 +75,12 @@ export function resolveRelayUrl(wssBaseUrl: string, webhookBaseUrl: string): str
  */
 function mapTwilioStatus(twilioStatus: string): CallStatus | null {
   switch (twilioStatus) {
+    case 'initiated':
     case 'queued':
+      return 'initiated';
     case 'ringing':
       return 'ringing';
+    case 'answered':
     case 'in-progress':
       return 'in_progress';
     case 'completed':
@@ -189,6 +193,8 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
   }
 
   try {
+    const wasTerminal = isTerminalState(session.status);
+
     // Build updates
     const updates: Parameters<typeof updateCallSession>[1] = {
       status: mappedStatus,
@@ -218,6 +224,10 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
     // Expire pending questions on terminal status
     if (isTerminal) {
       expirePendingQuestions(session.id);
+
+      if (!wasTerminal) {
+        fireCallCompletionNotifier(session.conversationId, session.id);
+      }
     }
 
     // Mark the claim as permanently processed so it never expires.
@@ -255,4 +265,3 @@ export async function handleConnectAction(_req: Request): Promise<Response> {
     },
   );
 }
-

package/src/cli/core-commands.ts

@@ -555,15 +555,23 @@ export function registerDoctorCommand(program: Command): void {
 
       // 11. WASM files
       const wasmFiles = [
-        'node_modules/web-tree-sitter/web-tree-sitter.wasm',
-        'node_modules/tree-sitter-bash/tree-sitter-bash.wasm',
+        { pkg: 'web-tree-sitter', file: 'web-tree-sitter.wasm' },
+        { pkg: 'tree-sitter-bash', file: 'tree-sitter-bash.wasm' },
       ];
       let wasmOk = true;
       const missingWasm: string[] = [];
       for (const wasm of wasmFiles) {
-        const fullPath = `${import.meta.dirname}/../../${wasm}`;
+        const dir = import.meta.dirname ?? __dirname;
+        let fullPath = `${dir}/../../node_modules/${wasm.pkg}/${wasm.file}`;
+        // In compiled binaries, fall back to Resources/ or next to the binary
+        if (!existsSync(fullPath) && dir.startsWith('/$bunfs/')) {
+          const { dirname: pathDirname, join: pathJoin } = await import('node:path');
+          const execDir = pathDirname(process.execPath);
+          const resourcesPath = pathJoin(execDir, '..', 'Resources', wasm.file);
+          fullPath = existsSync(resourcesPath) ? resourcesPath : pathJoin(execDir, wasm.file);
+        }
         if (!existsSync(fullPath)) {
-          missingWasm.push(wasm);
+          missingWasm.push(wasm.file);
           wasmOk = false;
         } else {
           try {

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "App Builder"
-description: "Create polished, professional local apps with HTML/CSS/JS"
+description: "Build interactive apps, dashboards, calculators, games, trackers, tools, landing pages, and data visualizations with HTML/CSS/JS. Use when the user says build, create, or make an app/dashboard/calculator/game."
 ---
 
 You are an expert app builder and visual designer. When the user asks you to create an app, tool, or utility, you immediately design a data schema, choose a stunning visual direction, build a self-contained HTML/CSS/JS interface, and open it — all in one step. You don't discuss or ask for permission to be creative. You ARE the designer: you pick the colors, the layout, the atmosphere, the micro-interactions. Your apps should make users stop and say "whoa" — they should feel designed, not generated.
@@ -1346,3 +1346,59 @@ Every app should include: search/filter, toast notifications for all CRUD operat
 - Never let a failed data operation silently pass — always show a toast or inline error message.
 - If the page loads with no data, show a designed empty state (`.v-empty-state`) — never a blank screen.
 - For forms, show validation errors inline next to the relevant field, not as an alert.
+
+## Actionable UI
+
+When the user wants to triage, manage, or bulk-act on a collection of items (emails, files, notifications, tasks, subscriptions, contacts), generate an interactive UI that lets them review, select, and act on items directly.
+
+### Pattern
+1. **Fetch data** — use the relevant tools to gather the items
+2. **Generate interactive UI** — render a `dynamic_page` with selectable items and action buttons
+3. **User selects + clicks action** — the UI sends a `surfaceAction` with an action ID and selected item IDs
+4. **Execute tools** — parse the action, call the appropriate tools
+5. **Update UI** — use `ui_update` to remove processed items and show feedback via `widgets.toast()`
+
+### HTML structure
+Choose the best layout for the data: grouped cards with checkboxes, data tables with selectable rows, kanban columns, stacked list items with inline actions, or any creative layout. The key constraint: items must be selectable and action buttons must call `sendAction` with the selected item IDs.
+
+### CSS building blocks
+- `.v-action-bar` — sticky bar at top, auto-hidden when nothing selected. Contains `.v-action-bar-count` and `.v-action-bar-buttons`
+- `.v-action-progress` — inline progress bar for bulk operations
+- `.v-group-header` / `.v-group-body` — collapsible grouped sections
+- `.v-row-removing` — fade-out + slide animation for processed items
+
+### Action data conventions
+- Use semantic action IDs: `archive`, `unsubscribe`, `delete`, `move`, `mark_read`
+- Always include selected item IDs: `sendAction("archive", { ids: ["msg_1", "msg_2"] })`
+
+### Processing flow
+1. Parse the `surfaceAction` to get the action ID and data
+2. Use `vellum.confirm(title, message)` for destructive actions before executing
+3. Call the relevant tools with the item IDs
+4. Use `ui_update` to remove processed items and update counts
+5. Show `widgets.toast()` for feedback
+
+### Error handling
+- Handle partial failures: remove successful items, toast count, keep failed items selectable for retry
+
+### Surface lifecycle
+- Use `ui_show` with `display: "panel"` to keep the surface open alongside chat
+- Use `widgets.groupedSelect()` for grouped multi-select with action bar
+- Use `widgets.removeItems()` to animate processed items out
+
+## Home Base
+
+Home Base starts from a prebuilt scaffold. When updating Home Base, preserve required task-lane anchors and apply changes through `app_file_edit` or `app_file_write`.
+
+Home Base buttons send prefilled natural-language prompts through `vellum.sendAction`. Treat these as normal user messages, not as direct execution commands.
+- For appearance changes: keep customization color-first, ask for explicit confirmation before applying a full-dashboard update.
+- For optional capability setup tasks (voice/computer control/ambient): keep them user-initiated and request permissions only when required for the chosen path.
+- If a prompt is underspecified, ask one brief follow-up and continue.
+
+## External Links
+
+When building apps with linkable items (search results, product cards, bookings), use `vellum.openLink(url, metadata)` to make them clickable. Construct deep-link URLs when possible (airline booking pages, product pages, hotel reservations). Include `metadata.provider` and `metadata.type` for context: `vellum.openLink("https://delta.com/book?flight=DL123", {provider: "delta", type: "booking"})`.
+
+## Branding
+
+A "Built on Vellum" badge is auto-injected into every dynamic page and app at the bottom-right corner. Do NOT add your own "Built on Vellum" or "Powered by Vellum" text — the badge is handled automatically by the rendering layer.

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

@@ -1,6 +1,6 @@
 ---
 name: "Document"
-description: "Document creation and editing for UI surfaces"
+description: "Write, draft, or compose long-form text (blog posts, articles, essays, reports, guides). Use when the user says write, draft, compose, or create a blog/article/essay."
 metadata: {"vellum": {"emoji": "📄"}}
 ---
 
@@ -11,8 +11,16 @@ Create and edit long-form documents using the built-in rich text editor. Documen
 - **document_create** — Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
 - **document_update** — Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
 
+## Workflow
+
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, *italic*, code blocks, tables, lists, blockquotes as appropriate.
+3. **CRITICAL — Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
+4. **Respond to edits**: When the user requests changes via the docked chat, use `document_update` with `replace` for full rewrites or `append` for additions.
+
 ## Usage Notes
 
-- Use `document_create` when the user asks to write a blog post, article, or any long-form content.
-- After creating a document, use `document_update` with the returned `surface_id` to stream or edit content.
 - The `mode` parameter on `document_update` defaults to `append`.
+- Documents are automatically saved and accessible via the Generated panel.
+- Users can manually edit documents at any time.
+- Write in clear, engaging prose. Use active voice, vary sentence structure, and break content into logical sections with descriptive headings.

package/src/config/bundled-skills/followups/icon.svg

@@ -0,0 +1,24 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" fill="#f5f5f5"/>
+  
+  <!-- Envelope body -->
+  <rect x="2" y="4" width="12" height="8" fill="#4a90e2" stroke="#2c5aa0" stroke-width="1"/>
+  
+  <!-- Envelope flap -->
+  <polygon points="2,4 8,8 14,4" fill="#357abd"/>
+  
+  <!-- Paper/message inside -->
+  <rect x="3" y="6" width="10" height="5" fill="#ffffff"/>
+  
+  <!-- Lines on paper -->
+  <line x1="4" y1="7" x2="12" y2="7" stroke="#d0d0d0" stroke-width="1"/>
+  <line x1="4" y1="8.5" x2="12" y2="8.5" stroke="#d0d0d0" stroke-width="1"/>
+  <line x1="4" y1="10" x2="10" y2="10" stroke="#d0d0d0" stroke-width="1"/>
+  
+  <!-- Clock overlay (top right) -->
+  <circle cx="11" cy="3" r="2.5" fill="#ff6b6b" stroke="#c92a2a" stroke-width="0.5"/>
+  
+  <!-- Clock hands -->
+  <line x1="11" y1="1.5" x2="11" y2="2.2" stroke="#ffffff" stroke-width="0.8" stroke-linecap="round"/>
+  <line x1="12.2" y1="3" x2="11.7" y2="3" stroke="#ffffff" stroke-width="0.8" stroke-linecap="round"/>
+</svg>

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

@@ -11,9 +11,13 @@ You are a unified messaging assistant with access to multiple platforms (Slack,
 
 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.
 
+### Public Ingress (required for all platforms)
+
+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.
+
 ### 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:
+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):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "google-oauth-setup"`.
    - Then call `skill_load` with `skill: "google-oauth-setup"`.
    - Tell the user: *"Gmail isn't connected yet. I've loaded a setup guide that will walk you through creating Google credentials and connecting your account."*
@@ -21,14 +25,14 @@ Before using any messaging tool, verify that the platform is connected by callin
 
 ### Slack
 1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "slack"`. The tool auto-fills Slack's OAuth endpoints and looks up any previously stored client credentials.
-2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill:
+2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "slack-oauth-setup"`.
    - Then call `skill_load` with `skill: "slack-oauth-setup"`.
    - Tell the user: *"Slack isn't connected yet. I've loaded a setup guide that will walk you through creating a Slack App and connecting your workspace."*
 3. **If the user provides client_id and client_secret directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "slack"`, `client_id`, and `client_secret`. Everything else is auto-filled. Note: Slack always requires a client_secret.
 
 ### Telegram
-Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** skill which automates the full setup:
+Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** skill (which depends on **public-ingress** for the webhook URL) which automates the full setup:
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "telegram-setup"`.
    - Then call `skill_load` with `skill: "telegram-setup"`.
    - Tell the user: *"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."*

package/src/config/bundled-skills/public-ingress/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: "Public Ingress"
+description: "Set up and manage ngrok-based public ingress for webhooks and OAuth callbacks via ingress.publicBaseUrl"
+user-invocable: true
+metadata: {"vellum": {"emoji": "🌍"}}
+---
+
+You are setting up and managing a public ingress tunnel so that external services (Telegram webhooks, OAuth callbacks, etc.) can reach the local Vellum gateway. This skill uses ngrok to create a secure tunnel and persists the public URL as `ingress.publicBaseUrl`.
+
+## Overview
+
+The Vellum gateway listens locally and needs a publicly reachable URL for:
+- Telegram webhook delivery
+- Google/Slack OAuth redirect callbacks
+- Any other inbound webhook traffic
+
+This skill installs ngrok, configures authentication, starts a tunnel, discovers the public URL, and saves it to the assistant's ingress config.
+
+## Step 1: Check Current Ingress Status
+
+First, check whether ingress is already configured:
+
+```bash
+vellum config get ingress.publicBaseUrl
+```
+
+Also determine the local gateway target. The gateway listens on `http://127.0.0.1:${GATEWAY_PORT:-7830}` by default.
+
+If `ingress.publicBaseUrl` is already set and the tunnel is running (check via `curl -s http://127.0.0.1:4040/api/tunnels`), tell the user the current status and ask if they want to reconfigure or if this is sufficient.
+
+## Step 2: Install ngrok
+
+Check if ngrok is installed:
+
+```bash
+ngrok version
+```
+
+If not installed, install it:
+
+**macOS (Homebrew):**
+```bash
+brew install ngrok/ngrok/ngrok
+```
+
+**Linux (snap):**
+```bash
+sudo snap install ngrok
+```
+
+**Linux (apt — alternative):**
+```bash
+curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
+echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
+sudo apt update && sudo apt install ngrok
+```
+
+After installation, verify with `ngrok version`.
+
+## Step 3: Authenticate ngrok
+
+Check if ngrok already has an auth token configured:
+
+```bash
+ngrok config check
+```
+
+If not authenticated:
+
+1. Tell the user: "You need an ngrok account to create tunnels. If you don't have one, sign up at https://dashboard.ngrok.com/signup — it's free."
+2. Once they have an account, ask them to paste their auth token directly in chat. They can find it at https://dashboard.ngrok.com/get-started/your-authtoken.
+
+3. Once the user provides the token, configure ngrok with it immediately:
+```bash
+ngrok config add-authtoken <token>
+```
+
+Verify authentication succeeded by checking `ngrok config check` again.
+
+## Step 4: Start the Tunnel
+
+Before starting, check for an existing ngrok process to avoid duplicates:
+
+```bash
+curl -s http://127.0.0.1:4040/api/tunnels 2>/dev/null
+```
+
+If a tunnel is already running, check whether it points to the correct local target. If so, skip to Step 5. If it points elsewhere, stop it first:
+
+```bash
+pkill -f ngrok || true
+sleep 1
+```
+
+Start ngrok in the background, tunneling to the local gateway:
+
+```bash
+nohup ngrok http http://127.0.0.1:${GATEWAY_PORT:-7830} --log=stdout > /tmp/ngrok.log 2>&1 &
+echo $! > /tmp/ngrok.pid
+```
+
+Wait a few seconds for the tunnel to establish:
+
+```bash
+sleep 3
+```
+
+## Step 5: Discover the Public URL
+
+Query the ngrok local API for the tunnel's public URL:
+
+```bash
+curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+tunnels = data.get('tunnels', [])
+for t in tunnels:
+    url = t.get('public_url', '')
+    if url.startswith('https://'):
+        print(url)
+        sys.exit(0)
+for t in tunnels:
+    url = t.get('public_url', '')
+    if url:
+        print(url)
+        sys.exit(0)
+print('ERROR: no tunnel found')
+sys.exit(1)
+"
+```
+
+If no tunnel is found, check `/tmp/ngrok.log` for errors and report them to the user.
+
+## Step 6: Persist the Ingress Setting
+
+Save the discovered public URL and enable ingress:
+
+```bash
+vellum config set ingress.publicBaseUrl "<public-url>"
+vellum config set ingress.enabled true
+```
+
+Verify it was saved:
+
+```bash
+vellum config get ingress.publicBaseUrl
+vellum config get ingress.enabled
+```
+
+## Step 7: Report Completion
+
+Summarize the setup:
+
+- **Public URL:** `<the-url>` (this is your `ingress.publicBaseUrl`)
+- **Local gateway:** `http://127.0.0.1:${GATEWAY_PORT:-7830}`
+- **ngrok dashboard:** http://127.0.0.1:4040
+
+Provide useful follow-up commands:
+
+- **Check tunnel status:** `curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "import sys,json; [print(t['public_url']) for t in json.load(sys.stdin)['tunnels']]"`
+- **View ngrok logs:** `cat /tmp/ngrok.log`
+- **Restart tunnel:** `pkill -f ngrok; sleep 1; nohup ngrok http http://127.0.0.1:${GATEWAY_PORT:-7830} --log=stdout > /tmp/ngrok.log 2>&1 &`
+- **Stop tunnel:** `pkill -f ngrok`
+- **Rotate URL:** Stop and restart ngrok (free tier assigns a new URL each time; update `ingress.publicBaseUrl` afterward)
+
+**Important:** On ngrok's free tier, the public URL changes every time the tunnel restarts. After restarting, re-run this skill or manually update `ingress.publicBaseUrl` and any registered webhooks (e.g., Telegram).
+
+## Troubleshooting
+
+### ngrok not installed
+Run the install commands in Step 2. On macOS, make sure Homebrew is installed first (`brew --version`).
+
+### Auth token invalid or expired
+Sign in to https://dashboard.ngrok.com, copy a fresh token from the "Your Authtoken" page, and re-run Step 3.
+
+### ngrok API (port 4040) not responding
+The ngrok process may not be running. Check with `ps aux | grep ngrok`. If not running, start it per Step 4. If running but 4040 is unresponsive, check `/tmp/ngrok.log` for errors.
+
+### Gateway not reachable on local target
+Ensure the Vellum gateway is running on `http://127.0.0.1:${GATEWAY_PORT:-7830}`. Check with `curl -s http://127.0.0.1:${GATEWAY_PORT:-7830}/health`. If not running, start the assistant daemon first.
+
+### "Too many connections" or tunnel limit errors
+ngrok's free tier allows one tunnel at a time. Stop any other ngrok tunnels before starting a new one.

package/src/config/bundled-skills/self-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "Self Upgrade"
-description: "Upgrade velly to the latest version, restart the daemon, and restart the gateway"
+description: "Upgrade vellum to the latest version, restart the daemon, and restart the gateway"
 user-invocable: true
 metadata: {"vellum": {"emoji": "⬆️"}}
 ---
@@ -15,16 +15,10 @@ vellum --version
 
 Save this value to report later.
 
-## Step 2: Install the latest velly
+## Step 2: Install the latest vellum
 
 ```bash
-bun update -g velly
-```
-
-If `velly` was not installed globally via bun, try:
-
-```bash
-npm update -g velly
+bun install -g vellum@latest
 ```
 
 After updating, verify the new version:
@@ -68,7 +62,7 @@ vellum daemon status
 ## After Upgrade
 
 Report back to the user with:
-- The previous and new velly version
+- The previous and new vellum version
 - Daemon status (running, PID)
 - Gateway status (restarted or not found)
 - Any errors encountered during the process

package/src/config/defaults.ts

@@ -228,7 +228,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     },
   },
   ingress: {
+    enabled: false,
     publicBaseUrl: '',
-    mode: 'gateway_only' as const,
   },
 };

package/src/config/schema.ts

@@ -9,7 +9,6 @@ const VALID_SANDBOX_BACKENDS = ['native', 'docker'] as const;
 const VALID_DOCKER_NETWORKS = ['none', 'bridge'] as const;
 const VALID_PERMISSIONS_MODES = ['legacy', 'strict'] as const;
 const VALID_CALL_PROVIDERS = ['twilio'] as const;
-const VALID_INGRESS_MODES = ['gateway_only', 'compat'] as const;
 
 export const TimeoutConfigSchema = z.object({
   shellMaxTimeoutSec: z
@@ -924,14 +923,12 @@ export const SkillsConfigSchema = z.object({
 });
 
 export const IngressConfigSchema = z.object({
+  enabled: z
+    .boolean({ error: 'ingress.enabled must be a boolean' })
+    .default(false),
   publicBaseUrl: z
     .string({ error: 'ingress.publicBaseUrl must be a string' })
     .default(''),
-  mode: z
-    .enum(VALID_INGRESS_MODES, {
-      error: `ingress.mode must be one of: ${VALID_INGRESS_MODES.join(', ')}`,
-    })
-    .default('gateway_only'),
 });
 
 export const AssistantConfigSchema = z.object({
@@ -1183,8 +1180,8 @@ export const AssistantConfigSchema = z.object({
     },
   }),
   ingress: IngressConfigSchema.default({
+    enabled: false,
     publicBaseUrl: '',
-    mode: 'gateway_only',
   }),
 }).superRefine((config, ctx) => {
   if (config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {