@vellumai/assistant 0.3.2 → 0.3.4

package/src/config/user-reference.ts

@@ -0,0 +1,29 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { getWorkspacePromptPath } from '../util/platform.js';
+
+const DEFAULT_USER_REFERENCE = 'my human';
+
+/**
+ * Resolve the name/reference the assistant uses when referring to
+ * the human it represents in external communications.
+ *
+ * Reads the "Preferred name/reference:" field from the Onboarding
+ * Snapshot section of USER.md.  Falls back to "my human" when the
+ * file is missing, unreadable, or the field is empty.
+ */
+export function resolveUserReference(): string {
+  const userPath = getWorkspacePromptPath('USER.md');
+  if (!existsSync(userPath)) return DEFAULT_USER_REFERENCE;
+
+  try {
+    const content = readFileSync(userPath, 'utf-8');
+    const match = content.match(/Preferred name\/reference:\s*(.+)/);
+    if (match && match[1].trim()) {
+      return match[1].trim();
+    }
+  } catch {
+    // Fallback on any read error
+  }
+
+  return DEFAULT_USER_REFERENCE;
+}

package/src/config/vellum-skills/catalog.json

@@ -0,0 +1,52 @@
+{
+  "description": "Manifest of first-party Vellum skills. Fetched from GitHub at runtime so the assistant can discover and install new skills maintained by Vellum.",
+  "version": 1,
+  "skills": [
+    {
+      "id": "chatgpt-import",
+      "name": "ChatGPT Import",
+      "description": "Import conversation history from ChatGPT into Vellum",
+      "emoji": "\ud83d\udce5"
+    },
+    {
+      "id": "deploy-fullstack-vercel",
+      "name": "Deploy Fullstack to Vercel",
+      "description": "Build and deploy a full-stack app (React frontend + Python/FastAPI backend) to Vercel as a serverless demo with seeded data",
+      "emoji": "\ud83d\ude80"
+    },
+    {
+      "id": "document-writer",
+      "name": "Document Writer",
+      "description": "Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor",
+      "emoji": "\ud83d\udcdd"
+    },
+    {
+      "id": "google-oauth-setup",
+      "name": "Google OAuth Setup",
+      "description": "Create Google Cloud OAuth credentials for Gmail integration using browser automation",
+      "emoji": "\ud83d\udd11",
+      "includes": ["browser", "public-ingress"]
+    },
+    {
+      "id": "slack-oauth-setup",
+      "name": "Slack OAuth Setup",
+      "description": "Create Slack App and OAuth credentials for Slack integration using browser automation",
+      "emoji": "\ud83d\udd11",
+      "includes": ["browser", "public-ingress"]
+    },
+    {
+      "id": "telegram-setup",
+      "name": "Telegram Setup",
+      "description": "Connect a Telegram bot to the Vellum Assistant gateway with automated webhook registration and credential storage",
+      "emoji": "\ud83e\udd16",
+      "includes": ["public-ingress"]
+    },
+    {
+      "id": "twilio-setup",
+      "name": "Twilio Setup",
+      "description": "Configure Twilio credentials and phone numbers for voice calls and SMS messaging",
+      "emoji": "\ud83d\udcf1",
+      "includes": ["public-ingress"]
+    }
+  ]
+}

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

@@ -103,12 +103,17 @@ Before reporting success, confirm the guardian binding was actually created. Sen
 
 ### Step 8: Report Success
 
+First, retrieve the bot identity by sending a `telegram_config` IPC message with `action: "get"` and reading the `botUsername` field from the response.
+
 Summarize what was done:
+- Bot identity: @{botUsername}
 - Bot verified and credentials stored securely via daemon
 - Webhook registration: handled automatically by the gateway
 - Bot commands registered: /new, /guardian_verify
-- Guardian identity verified (if completed and binding confirmed)
+- Guardian identity: {verified | not configured}
+- Guardian verification status: {verified via challenge | skipped}
 - Routing configuration validated
+- To re-check guardian status later, send `guardian_verification` with `action: "status"` and `channel: "telegram"`
 
 The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 

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

@@ -82,7 +82,14 @@ If the user wants to buy a new number through Twilio, send:
 - `areaCode` is optional — ask the user if they have a preferred area code
 - `country` defaults to `"US"` — ask if they want a different country (ISO 3166-1 alpha-2)
 
-The daemon provisions the number via the Twilio API and automatically assigns it to the assistant. The response includes the new `phoneNumber`.
+The daemon provisions the number via the Twilio API, automatically assigns it to the assistant (persisting to both secure storage and config), and configures Twilio webhooks (voice, status callback, SMS) if a public ingress URL is available. The response includes the new `phoneNumber`. No separate `assign_number` call is needed.
+
+**Webhook auto-configuration:** When `ingress.publicBaseUrl` is configured, the daemon automatically sets the following webhooks on the Twilio phone number:
+- Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
+- Voice status callback: `{publicBaseUrl}/webhooks/twilio/status`
+- SMS webhook: `{publicBaseUrl}/webhooks/twilio/sms`
+
+If ingress is not yet configured, webhook setup is skipped gracefully — the number is still assigned and usable once ingress is set up later.
 
 **Trial account note:** Twilio trial accounts come with one free phone number. Check "Active Numbers" in the Twilio Console first before provisioning.
 
@@ -109,7 +116,7 @@ Then assign the chosen number:
 }
 ```
 
-The phone number must be in E.164 format.
+The phone number must be in E.164 format. Like `provision_number`, `assign_number` also auto-configures Twilio webhooks when a public ingress URL is available.
 
 ### Option C: Manual Entry
 
@@ -146,13 +153,13 @@ If not configured, load and run the public-ingress skill:
 skill_load skill=public-ingress
 ```
 
-**Twilio webhook endpoints (handled automatically by the gateway):**
+**Twilio webhook endpoints (auto-configured on provision/assign):**
 - Voice webhook: `{publicBaseUrl}/webhooks/twilio/voice`
 - Voice status callback: `{publicBaseUrl}/webhooks/twilio/status`
 - ConversationRelay WebSocket: `{publicBaseUrl}/webhooks/twilio/relay` (wss://)
 - SMS webhook: `{publicBaseUrl}/webhooks/twilio/sms`
 
-No manual Twilio webhook configuration is needed — webhook URLs are registered dynamically.
+Webhook URLs are automatically configured on the Twilio phone number when `provision_number` or `assign_number` is called with a valid ingress URL. No manual Twilio Console webhook configuration is needed.
 
 ## Step 5: Verify Setup
 
@@ -164,6 +171,44 @@ Confirm:
 
 Tell the user: **"Twilio is configured. Your assistant's phone number is {phoneNumber}. This number is used for both voice calls and SMS messaging."**
 
+## Step 5.5: Guardian Verification (SMS)
+
+Now link the user's phone number as the trusted SMS guardian for this assistant. Tell the user: "Now let's verify your guardian identity for SMS. This links your phone number as the trusted guardian for SMS messaging."
+
+1. Send the `guardian_verification` IPC message with `action: "create_challenge"` and `channel: "sms"`:
+
+```json
+{
+  "type": "guardian_verification",
+  "action": "create_challenge",
+  "channel": "sms"
+}
+```
+
+2. The daemon returns a `guardian_verification_response` with `success: true`, `secret`, and `instruction`. Display the instruction to the user. It will look like: "Send `/guardian_verify <secret>` to your bot via SMS within 10 minutes."
+
+3. Wait for the user to confirm they have sent the verification code via SMS to the assistant's phone number.
+
+4. Check verification status by sending `guardian_verification` with `action: "status"` and `channel: "sms"`:
+
+```json
+{
+  "type": "guardian_verification",
+  "action": "status",
+  "channel": "sms"
+}
+```
+
+5. If `bound` is `true`: "Guardian verified! Your phone number is now the trusted SMS guardian."
+
+6. If `bound` is `false` and the user claims they sent the code: "The verification doesn't appear to have succeeded. Let's generate a new challenge." Repeat from substep 1.
+
+**Note:** Guardian verification is optional but recommended. If the user declines or wants to skip, proceed to Step 6 without blocking.
+
+To re-check guardian status later, send `guardian_verification` with `action: "status"` and `channel: "sms"`.
+
+Report the guardian verification result: **"Guardian identity: {verified | not configured}."**
+
 ## Step 6: Enable Features
 
 Now that Twilio is configured, the user can enable the features that depend on it:

package/src/daemon/auth-manager.ts

@@ -0,0 +1,103 @@
+/**
+ * Manages daemon-level authentication: session token lifecycle,
+ * per-socket auth state, and auth timeouts.
+ */
+import * as net from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { getSessionTokenPath } from '../util/platform.js';
+import { hasNoAuthOverride } from './connection-policy.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('auth-manager');
+
+export const AUTH_TIMEOUT_MS = 5_000;
+
+export class AuthManager {
+  private sessionToken = '';
+  private authenticatedSockets = new Set<net.Socket>();
+  private authTimeouts = new Map<net.Socket, ReturnType<typeof setTimeout>>();
+
+  /** Initialize the session token — reuse from disk or generate a new one. */
+  initToken(): void {
+    const tokenPath = getSessionTokenPath();
+    let existingToken: string | null = null;
+    try {
+      const raw = readFileSync(tokenPath, 'utf-8').trim();
+      if (raw.length >= 32) existingToken = raw;
+    } catch { /* file doesn't exist yet */ }
+
+    if (existingToken) {
+      this.sessionToken = existingToken;
+      log.info({ tokenPath }, 'Reusing existing session token');
+    } else {
+      this.sessionToken = randomBytes(32).toString('hex');
+      writeFileSync(tokenPath, this.sessionToken, { mode: 0o600 });
+      chmodSync(tokenPath, 0o600);
+      log.info({ tokenPath }, 'New session token generated');
+    }
+  }
+
+  isAuthenticated(socket: net.Socket): boolean {
+    return this.authenticatedSockets.has(socket);
+  }
+
+  /** Returns true if VELLUM_DAEMON_NOAUTH bypass is active. */
+  shouldAutoAuth(): boolean {
+    return hasNoAuthOverride();
+  }
+
+  markAuthenticated(socket: net.Socket): void {
+    this.authenticatedSockets.add(socket);
+  }
+
+  /** Validate a token and authenticate the socket. Returns true on success. */
+  authenticate(socket: net.Socket, token: string): boolean {
+    if (token === this.sessionToken) {
+      this.authenticatedSockets.add(socket);
+      return true;
+    }
+    log.warn('Client provided invalid auth token');
+    return false;
+  }
+
+  /** Start the auth timeout for a newly connected socket. */
+  startTimeout(socket: net.Socket, onTimeout: () => void): void {
+    const timer = setTimeout(() => {
+      if (!this.authenticatedSockets.has(socket)) {
+        log.warn('Client failed to authenticate within timeout, disconnecting');
+        onTimeout();
+      }
+    }, AUTH_TIMEOUT_MS);
+    this.authTimeouts.set(socket, timer);
+  }
+
+  /** Clear the auth timeout (called when the first message arrives). */
+  clearTimeout(socket: net.Socket): void {
+    const timer = this.authTimeouts.get(socket);
+    if (timer) {
+      clearTimeout(timer);
+      this.authTimeouts.delete(socket);
+    }
+  }
+
+  /** Remove all auth state for a disconnected socket. */
+  cleanupSocket(socket: net.Socket): void {
+    this.clearTimeout(socket);
+    this.authenticatedSockets.delete(socket);
+  }
+
+  /** Tear down all auth state on server stop. */
+  cleanupAll(): void {
+    for (const timer of this.authTimeouts.values()) {
+      clearTimeout(timer);
+    }
+    this.authTimeouts.clear();
+    this.authenticatedSockets.clear();
+  }
+
+  /** Iterate over authenticated sockets (for broadcasting). */
+  getAuthenticatedSockets(): Set<net.Socket> {
+    return this.authenticatedSockets;
+  }
+}

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

@@ -897,7 +897,14 @@ export class ComputerUseSession {
     decision: UserDecision,
     selectedPattern?: string,
     selectedScope?: string,
+    decisionContext?: string,
   ): void {
-    this.prompter?.resolveConfirmation(requestId, decision, selectedPattern, selectedScope);
+    this.prompter?.resolveConfirmation(
+      requestId,
+      decision,
+      selectedPattern,
+      selectedScope,
+      decisionContext,
+    );
   }
 }

package/src/daemon/config-watcher.ts

@@ -0,0 +1,253 @@
+/**
+ * File watchers and config reload logic extracted from DaemonServer.
+ * Watches workspace files (config, prompts), protected directory
+ * (trust rules, secret allowlist), and skills directories for changes.
+ */
+import { existsSync, readdirSync, watch, type FSWatcher } from 'node:fs';
+import { join } from 'node:path';
+import { getRootDir, getWorkspaceDir, getWorkspaceSkillsDir } from '../util/platform.js';
+import { getConfig, invalidateConfigCache } from '../config/loader.js';
+import { initializeProviders } from '../providers/registry.js';
+import { clearCache as clearTrustCache } from '../permissions/trust-store.js';
+import { resetAllowlist, validateAllowlistFile } from '../security/secret-allowlist.js';
+import { clearEmbeddingBackendCache } from '../memory/embedding-backend.js';
+import { DebouncerMap } from '../util/debounce.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('config-watcher');
+
+export class ConfigWatcher {
+  private watchers: FSWatcher[] = [];
+  private debounceTimers = new DebouncerMap({
+    defaultDelayMs: 200,
+    maxEntries: 1000,
+    protectedKeyPrefix: '__',
+  });
+  private suppressReload = false;
+  private lastFingerprint = '';
+  private lastRefreshTime = 0;
+
+  static readonly REFRESH_INTERVAL_MS = 30_000;
+
+  /** Expose the debounce timers so handlers can schedule debounced work. */
+  get timers(): DebouncerMap {
+    return this.debounceTimers;
+  }
+
+  get suppressConfigReload(): boolean {
+    return this.suppressReload;
+  }
+
+  set suppressConfigReload(value: boolean) {
+    this.suppressReload = value;
+  }
+
+  get lastConfigRefreshTime(): number {
+    return this.lastRefreshTime;
+  }
+
+  set lastConfigRefreshTime(value: number) {
+    this.lastRefreshTime = value;
+  }
+
+  /** Compute a fingerprint of the current config for change detection. */
+  configFingerprint(config: ReturnType<typeof getConfig>): string {
+    return JSON.stringify(config);
+  }
+
+  /** Initialize the config fingerprint (call after first config load). */
+  initFingerprint(config: ReturnType<typeof getConfig>): void {
+    this.lastFingerprint = this.configFingerprint(config);
+  }
+
+  /** Update the fingerprint to match the current config. */
+  updateFingerprint(): void {
+    this.lastFingerprint = this.configFingerprint(getConfig());
+    this.lastRefreshTime = Date.now();
+  }
+
+  /**
+   * Reload config from disk + secure storage, and refresh providers only
+   * when effective config values (including API keys) have changed.
+   * Returns true if config actually changed.
+   */
+  refreshConfigFromSources(): boolean {
+    invalidateConfigCache();
+    const config = getConfig();
+    const fingerprint = this.configFingerprint(config);
+    if (fingerprint === this.lastFingerprint) {
+      return false;
+    }
+    clearTrustCache();
+    clearEmbeddingBackendCache();
+    const isFirstInit = this.lastFingerprint === '';
+    initializeProviders(config);
+    this.lastFingerprint = fingerprint;
+    return !isFirstInit;
+  }
+
+  /**
+   * Start all file watchers. `onSessionEvict` is called when watched
+   * files change and sessions need to be evicted for reload.
+   */
+  start(onSessionEvict: () => void): void {
+    const workspaceDir = getWorkspaceDir();
+    const protectedDir = join(getRootDir(), 'protected');
+
+    const workspaceHandlers: Record<string, () => void> = {
+      'config.json': () => {
+        if (this.suppressReload) return;
+        try {
+          const changed = this.refreshConfigFromSources();
+          if (changed) onSessionEvict();
+        } catch (err) {
+          log.error({ err, configPath: join(workspaceDir, 'config.json') }, 'Failed to reload config after file change. Previous config remains active.');
+        }
+      },
+      'SOUL.md': () => onSessionEvict(),
+      'IDENTITY.md': () => onSessionEvict(),
+      'USER.md': () => onSessionEvict(),
+      'LOOKS.md': () => onSessionEvict(),
+    };
+
+    const protectedHandlers: Record<string, () => void> = {
+      'trust.json': () => {
+        clearTrustCache();
+      },
+      'secret-allowlist.json': () => {
+        resetAllowlist();
+        try {
+          const errors = validateAllowlistFile();
+          if (errors && errors.length > 0) {
+            for (const e of errors) {
+              log.warn({ index: e.index, pattern: e.pattern }, `Invalid regex in secret-allowlist.json: ${e.message}`);
+            }
+          }
+        } catch (err) {
+          log.warn({ err }, 'Failed to validate secret-allowlist.json');
+        }
+      },
+    };
+
+    const watchDir = (dir: string, handlers: Record<string, () => void>, label: string): void => {
+      try {
+        const watcher = watch(dir, (_eventType, filename) => {
+          if (!filename) return;
+          const file = String(filename);
+          if (!handlers[file]) return;
+          this.debounceTimers.schedule(`file:${file}`, () => {
+            log.info({ file }, 'File changed, reloading');
+            handlers[file]();
+          });
+        });
+        this.watchers.push(watcher);
+        log.info({ dir }, `Watching ${label}`);
+      } catch (err) {
+        log.warn({ err, dir }, `Failed to watch ${label}. Hot-reload will be unavailable.`);
+      }
+    };
+
+    watchDir(workspaceDir, workspaceHandlers, 'workspace directory for config/prompt changes');
+    if (existsSync(protectedDir)) {
+      watchDir(protectedDir, protectedHandlers, 'protected directory for trust/allowlist changes');
+    }
+
+    this.startSkillsWatchers(onSessionEvict);
+  }
+
+  stop(): void {
+    this.debounceTimers.cancelAll();
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+  }
+
+  private startSkillsWatchers(onSessionEvict: () => void): void {
+    const skillsDir = getWorkspaceSkillsDir();
+    if (!existsSync(skillsDir)) return;
+
+    const scheduleSkillsReload = (file: string): void => {
+      this.debounceTimers.schedule(`skills:${file}`, () => {
+        log.info({ file }, 'Skill file changed, reloading');
+        onSessionEvict();
+      });
+    };
+
+    try {
+      const recursiveWatcher = watch(skillsDir, { recursive: true }, (_eventType, filename) => {
+        scheduleSkillsReload(filename ? String(filename) : '(unknown)');
+      });
+      this.watchers.push(recursiveWatcher);
+      log.info({ dir: skillsDir }, 'Watching skills directory recursively');
+      return;
+    } catch (err) {
+      log.info({ err, dir: skillsDir }, 'Recursive skills watch unavailable; using per-directory watchers');
+    }
+
+    const childWatchers = new Map<string, FSWatcher>();
+
+    const watchDir = (dirPath: string, onChange: (filename: string) => void): FSWatcher | null => {
+      try {
+        const watcher = watch(dirPath, (_eventType, filename) => {
+          onChange(filename ? String(filename) : '(unknown)');
+        });
+        this.watchers.push(watcher);
+        return watcher;
+      } catch (err) {
+        log.warn({ err, dirPath }, 'Failed to watch skills directory');
+        return null;
+      }
+    };
+
+    const removeWatcher = (watcher: FSWatcher): void => {
+      const idx = this.watchers.indexOf(watcher);
+      if (idx !== -1) {
+        this.watchers.splice(idx, 1);
+      }
+    };
+
+    const refreshChildWatchers = (): void => {
+      const nextChildDirs = new Set<string>();
+
+      try {
+        const entries = readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          const childDir = join(skillsDir, entry.name);
+          nextChildDirs.add(childDir);
+
+          if (childWatchers.has(childDir)) continue;
+
+          const watcher = watchDir(childDir, (filename) => {
+            const label = filename === '(unknown)' ? entry.name : `${entry.name}/${filename}`;
+            scheduleSkillsReload(label);
+          });
+          if (watcher) {
+            childWatchers.set(childDir, watcher);
+          }
+        }
+      } catch (err) {
+        log.warn({ err, skillsDir }, 'Failed to enumerate skill directories');
+        return;
+      }
+
+      for (const [childDir, watcher] of childWatchers.entries()) {
+        if (nextChildDirs.has(childDir)) continue;
+        watcher.close();
+        childWatchers.delete(childDir);
+        removeWatcher(watcher);
+      }
+    };
+
+    const rootWatcher = watchDir(skillsDir, (filename) => {
+      scheduleSkillsReload(filename);
+      refreshChildWatchers();
+    });
+
+    if (!rootWatcher) return;
+
+    refreshChildWatchers();
+    log.info({ dir: skillsDir }, 'Watching skills directory with non-recursive fallback');
+  }
+}