@vellumai/assistant 0.3.19 → 0.3.21

package/src/tools/mcp/mcp-tool-factory.ts

@@ -0,0 +1,100 @@
+import type { McpServerConfig } from '../../config/mcp-schema.js';
+import type { McpServerManager } from '../../mcp/manager.js';
+import { RiskLevel } from '../../permissions/types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+
+const riskMap: Record<string, RiskLevel> = {
+  low: RiskLevel.Low,
+  medium: RiskLevel.Medium,
+  high: RiskLevel.High,
+};
+
+/**
+ * Create a namespaced tool name to prevent collisions across MCP servers
+ * and with core/skill tools.
+ */
+export function mcpToolName(serverId: string, toolName: string): string {
+  return `mcp__${serverId}__${toolName}`;
+}
+
+/**
+ * Parse a namespaced MCP tool name back into serverId and original tool name.
+ * Returns null if the name doesn't match the MCP naming convention.
+ */
+export function parseMcpToolName(name: string): { serverId: string; toolName: string } | null {
+  if (!name.startsWith('mcp__')) return null;
+  const prefixRemoved = name.slice(5); // remove 'mcp__'
+  const firstSep = prefixRemoved.indexOf('__');
+  if (firstSep === -1) return null;
+  return {
+    serverId: prefixRemoved.slice(0, firstSep),
+    toolName: prefixRemoved.slice(firstSep + 2),
+  };
+}
+
+export interface McpToolMetadata {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Create a Tool object from MCP tool metadata.
+ * The tool delegates execution to the McpServerManager.
+ */
+export function createMcpTool(
+  metadata: McpToolMetadata,
+  serverId: string,
+  serverConfig: McpServerConfig,
+  manager: McpServerManager,
+): Tool {
+  const namespacedName = mcpToolName(serverId, metadata.name);
+  const riskLevel = riskMap[serverConfig.defaultRiskLevel] ?? RiskLevel.High;
+
+  return {
+    name: namespacedName,
+    description: metadata.description,
+    category: 'mcp',
+    defaultRiskLevel: riskLevel,
+    origin: 'mcp',
+    ownerMcpServerId: serverId,
+    executionTarget: 'host',
+
+    getDefinition(): ToolDefinition {
+      return {
+        name: namespacedName,
+        description: metadata.description,
+        input_schema: metadata.inputSchema as ToolDefinition['input_schema'],
+      };
+    },
+
+    async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+      try {
+        const result = await manager.callTool(serverId, metadata.name, input);
+        return {
+          content: result.content,
+          isError: result.isError,
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: `MCP tool execution failed: ${message}`,
+          isError: true,
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Create Tool objects from all tools provided by an MCP server.
+ */
+export function createMcpToolsFromServer(
+  tools: McpToolMetadata[],
+  serverId: string,
+  serverConfig: McpServerConfig,
+  manager: McpServerManager,
+): Tool[] {
+  return tools.map((tool) => createMcpTool(tool, serverId, serverConfig, manager));
+}

package/src/tools/network/script-proxy/session-manager.ts

@@ -373,7 +373,6 @@ export async function stopSession(sessionId: ProxySessionId): Promise<void> {
  */
 export function getSessionEnv(
   sessionId: ProxySessionId,
-  options?: { dockerMode?: boolean },
 ): ProxyEnvVars {
   const managed = sessions.get(sessionId);
   if (!managed) throw new Error(`Session not found: ${sessionId}`);
@@ -384,10 +383,7 @@ export function getSessionEnv(
   // Touch the idle timer on access
   resetIdleTimer(managed);
 
-  // Inside Docker, 127.0.0.1 is the container's own loopback — use
-  // host.docker.internal so traffic reaches the host-side proxy.
-  const host = options?.dockerMode ? 'host.docker.internal' : '127.0.0.1';
-  const proxyUrl = `http://${host}:${managed.session.port}`;
+  const proxyUrl = `http://127.0.0.1:${managed.session.port}`;
   const env: ProxyEnvVars = {
     HTTP_PROXY: proxyUrl,
     HTTPS_PROXY: proxyUrl,

package/src/tools/registry.ts

@@ -121,7 +121,7 @@ export function registerSkillTools(newTools: Tool[]): Tool[] {
   for (const tool of newTools) {
     const existing = tools.get(tool.name);
     if (existing) {
-      const existingIsCore = existing.origin !== 'skill';
+      const existingIsCore = existing.origin === 'core' || !existing.origin;
       if (existingIsCore) {
         log.warn(
           { toolName: tool.name, skillId: tool.ownerSkillId },
@@ -176,6 +176,69 @@ export function unregisterSkillTools(skillId: string): void {
   }
 }
 
+/**
+ * Register multiple MCP-origin tools at once.
+ * Skips any tool whose name collides with a core tool (logs a warning).
+ * Throws if a tool name collides with a tool owned by a different MCP server.
+ */
+export function registerMcpTools(newTools: Tool[]): Tool[] {
+  const accepted: Tool[] = [];
+  for (const tool of newTools) {
+    const existing = tools.get(tool.name);
+    if (existing) {
+      const existingIsCore = existing.origin === 'core' || !existing.origin;
+      if (existingIsCore) {
+        log.warn(
+          { toolName: tool.name, serverId: tool.ownerMcpServerId },
+          `MCP server "${tool.ownerMcpServerId}" tried to register tool "${tool.name}" which conflicts with a core tool. Skipping.`,
+        );
+        continue;
+      }
+      if (existing.origin === 'skill') {
+        log.warn(
+          { toolName: tool.name, serverId: tool.ownerMcpServerId, skillId: existing.ownerSkillId },
+          `MCP server "${tool.ownerMcpServerId}" tried to register tool "${tool.name}" which conflicts with skill tool from "${existing.ownerSkillId}". Skipping.`,
+        );
+        continue;
+      }
+      if (existing.origin === 'mcp' && existing.ownerMcpServerId !== tool.ownerMcpServerId) {
+        throw new Error(
+          `MCP tool "${tool.name}" is already registered by MCP server "${existing.ownerMcpServerId}"`,
+        );
+      }
+    }
+    accepted.push(tool);
+  }
+
+  for (const tool of accepted) {
+    tools.set(tool.name, tool);
+    log.info({ name: tool.name, ownerMcpServerId: tool.ownerMcpServerId }, 'MCP tool registered');
+  }
+
+  return accepted;
+}
+
+/**
+ * Unregister all tools belonging to a specific MCP server.
+ */
+export function unregisterMcpTools(serverId: string): void {
+  for (const [name, tool] of tools) {
+    if (tool.origin === 'mcp' && tool.ownerMcpServerId === serverId) {
+      tools.delete(name);
+      log.info({ name, serverId }, 'MCP tool unregistered');
+    }
+  }
+}
+
+/**
+ * Return the names of all currently registered MCP-origin tools.
+ */
+export function getMcpToolNames(): string[] {
+  return Array.from(tools.values())
+    .filter((t) => t.origin === 'mcp')
+    .map((t) => t.name);
+}
+
 /**
  * Return the names of all currently registered skill-origin tools.
  */

package/src/tools/skills/load.ts

@@ -1,3 +1,6 @@
+import { isAssistantFeatureFlagEnabled } from '../../config/assistant-feature-flags.js';
+import { getConfig } from '../../config/loader.js';
+import { skillFlagKey } from '../../config/skill-state.js';
 import type { SkillSummary } from '../../config/skills.js';
 import { loadSkillBySelector, loadSkillCatalog } from '../../config/skills.js';
 import { RiskLevel } from '../../permissions/types.js';
@@ -46,6 +49,15 @@ export class SkillLoadTool implements Tool {
 
     const skill = loaded.skill;
 
+    // Assistant feature flag gate: reject loading if the skill's flag is OFF
+    const config = getConfig();
+    if (!isAssistantFeatureFlagEnabled(skillFlagKey(skill.id), config)) {
+      return {
+        content: `Error: skill "${skill.id}" is currently unavailable (disabled by feature flag)`,
+        isError: true,
+      };
+    }
+
     // Load catalog for include validation and child metadata output
     let catalogIndex: Map<string, SkillSummary> | undefined;
     if (skill.includes && skill.includes.length > 0) {
@@ -83,14 +95,15 @@ export class SkillLoadTool implements Tool {
       const childLines: string[] = [];
       for (const childId of skill.includes) {
         const child = catalogIndex.get(childId);
-        if (child) {
-          childLines.push(`  - ${child.id}: ${child.name} — ${child.description} (${child.skillFilePath})`);
-
-          // Load the included skill's body content
-          const childLoaded = loadSkillBySelector(childId);
-          if (childLoaded.skill && childLoaded.skill.body.length > 0) {
-            includedBodies.push(`--- Included Skill: ${childLoaded.skill.name} (${childId}) ---\n${childLoaded.skill.body}`);
-          }
+        if (!child) continue;
+        if (!isAssistantFeatureFlagEnabled(skillFlagKey(childId), config)) continue;
+
+        childLines.push(`  - ${child.id}: ${child.name} — ${child.description} (${child.skillFilePath})`);
+
+        // Load the included skill's body content
+        const childLoaded = loadSkillBySelector(childId);
+        if (childLoaded.skill && childLoaded.skill.body.length > 0) {
+          includedBodies.push(`--- Included Skill: ${childLoaded.skill.name} (${childId}) ---\n${childLoaded.skill.body}`);
         }
       }
       immediateChildrenSection = `Included Skills (immediate):\n${childLines.join('\n')}`;
@@ -113,6 +126,7 @@ export class SkillLoadTool implements Tool {
       for (const childId of skill.includes) {
         const child = catalogIndex.get(childId);
         if (!child) continue;
+        if (!isAssistantFeatureFlagEnabled(skillFlagKey(childId), config)) continue;
         let childHash: string | undefined;
         try {
           childHash = computeSkillVersionHash(child.directoryPath);

package/src/tools/system/avatar-generator.ts

@@ -0,0 +1,119 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { getConfig } from '../../config/loader.js';
+import { generateImage, mapGeminiError } from '../../media/gemini-image-service.js';
+import { RiskLevel } from '../../permissions/types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { getLogger } from '../../util/logger.js';
+import { getWorkspaceDir } from '../../util/platform.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+
+const log = getLogger('avatar-generator');
+
+const TOOL_NAME = 'set_avatar';
+
+/** Canonical path where the custom avatar PNG is stored. */
+function getAvatarPath(): string {
+  return join(getWorkspaceDir(), 'data', 'avatar', 'custom-avatar.png');
+}
+
+export const setAvatarTool: Tool = {
+  name: TOOL_NAME,
+  description:
+    'Generate a custom avatar image from a text description. ' +
+    'Saves the result as the assistant\'s avatar.',
+  category: 'system',
+  defaultRiskLevel: RiskLevel.Low,
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: TOOL_NAME,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          description: {
+            type: 'string',
+            description:
+              'A text description of the desired avatar appearance, ' +
+              'e.g. "a friendly purple cat with green eyes wearing a tiny hat".',
+          },
+        },
+        required: ['description'],
+      },
+    };
+  },
+
+  async execute(
+    input: Record<string, unknown>,
+    _context: ToolContext,
+  ): Promise<ToolExecutionResult> {
+    const description = input.description;
+    if (typeof description !== 'string' || description.trim() === '') {
+      return {
+        content: 'Error: description is required and must be a non-empty string.',
+        isError: true,
+      };
+    }
+
+    const config = getConfig();
+    const apiKey = config.apiKeys.gemini ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      return {
+        content: 'No Gemini API key configured. Please add your Gemini API key in Settings → Models & Services, or set the GEMINI_API_KEY environment variable.',
+        isError: true,
+      };
+    }
+
+    try {
+      log.info({ description: description.trim() }, 'Generating avatar via Gemini');
+
+      const prompt =
+        `Create an avatar image based on this description: ${description.trim()}\n\n` +
+        'Style: cute, friendly, work-safe illustration. ' +
+        'Vibrant but soft colors. Simple and recognizable at small sizes (28px). ' +
+        'Circular or rounded composition filling the canvas. ' +
+        'Subtle background color (not white or transparent).';
+
+      const result = await generateImage(apiKey, {
+        prompt,
+        mode: 'generate',
+        model: config.imageGenModel,
+      });
+
+      if (result.images.length === 0) {
+        return {
+          content: 'Error: Gemini returned no image data. Please try again.',
+          isError: true,
+        };
+      }
+
+      const image = result.images[0];
+      const pngBuffer = Buffer.from(image.dataBase64, 'base64');
+
+      const avatarPath = getAvatarPath();
+      const avatarDir = dirname(avatarPath);
+
+      mkdirSync(avatarDir, { recursive: true });
+      writeFileSync(avatarPath, pngBuffer);
+
+      log.info({ avatarPath }, 'Avatar saved successfully');
+
+      // Side-effect hook in tool-side-effects.ts broadcasts avatar_updated to all clients.
+
+      return {
+        content: 'Avatar updated! Your new avatar will appear shortly.',
+        isError: false,
+      };
+    } catch (error) {
+      const message = mapGeminiError(error);
+      log.error({ error: message }, 'Avatar generation failed');
+
+      return {
+        content: `Avatar generation failed: ${message}`,
+        isError: true,
+      };
+    }
+  },
+};

package/src/tools/system/navigate-settings.ts

@@ -0,0 +1,65 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+
+const SETTINGS_TABS = [
+  'Voice',
+  'Connect',
+  'Trust',
+  'Model',
+  'Scheduling',
+  'Parental',
+] as const;
+
+type SettingsTab = (typeof SETTINGS_TABS)[number];
+
+export class NavigateSettingsTabTool implements Tool {
+  name = 'navigate_settings_tab';
+  description =
+    'Open the Vellum settings panel to a specific tab (e.g. Voice, Connect, Trust). ' +
+    'Use this when the user needs to review or adjust settings visually.';
+  category = 'system';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          tab: {
+            type: 'string',
+            enum: [...SETTINGS_TABS],
+            description: 'The settings tab to navigate to',
+          },
+        },
+        required: ['tab'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const tab = input.tab as string;
+    if (!SETTINGS_TABS.includes(tab as SettingsTab)) {
+      return {
+        content: `Error: unknown tab "${tab}". Valid tabs: ${SETTINGS_TABS.join(', ')}`,
+        isError: true,
+      };
+    }
+
+    if (context.sendToClient) {
+      context.sendToClient({
+        type: 'navigate_settings',
+        tab,
+      });
+    }
+
+    return {
+      content: `Opened settings to the ${tab} tab.`,
+      isError: false,
+    };
+  }
+}
+
+export const navigateSettingsTabTool = new NavigateSettingsTabTool();

package/src/tools/system/open-system-settings.ts

@@ -0,0 +1,75 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+
+const PANES = {
+  microphone: {
+    url: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone',
+    label: 'Microphone privacy',
+    instruction: 'Please toggle Vellum Assistant on.',
+  },
+  speech_recognition: {
+    url: 'x-apple.systempreferences:com.apple.preference.security?Privacy_SpeechRecognition',
+    label: 'Speech Recognition privacy',
+    instruction: 'Please toggle Vellum Assistant on.',
+  },
+} as const;
+
+type PaneName = keyof typeof PANES;
+
+const VALID_PANES = Object.keys(PANES) as PaneName[];
+
+export class OpenSystemSettingsTool implements Tool {
+  name = 'open_system_settings';
+  description =
+    'Open a specific macOS System Settings pane (e.g. Microphone or Speech Recognition privacy). ' +
+    'Use this to guide the user through granting permissions that can only be toggled in System Settings.';
+  category = 'system';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          pane: {
+            type: 'string',
+            enum: [...VALID_PANES],
+            description: 'The System Settings pane to open',
+          },
+        },
+        required: ['pane'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const pane = input.pane as string;
+    if (!VALID_PANES.includes(pane as PaneName)) {
+      return {
+        content: `Error: unknown pane "${pane}". Valid panes: ${VALID_PANES.join(', ')}`,
+        isError: true,
+      };
+    }
+
+    const meta = PANES[pane as PaneName];
+
+    // Send open_url IPC to the client — the x-apple.systempreferences: scheme
+    // opens System Settings directly without a browser confirmation dialog.
+    if (context.sendToClient) {
+      context.sendToClient({
+        type: 'open_url',
+        url: meta.url,
+      });
+    }
+
+    return {
+      content: `Opened System Settings to ${meta.label}. ${meta.instruction}`,
+      isError: false,
+    };
+  }
+}
+
+export const openSystemSettingsTool = new OpenSystemSettingsTool();