@vellumai/assistant 0.4.26 → 0.4.29

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

@@ -1,29 +1,32 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+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';
+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 log = getLogger("avatar-generator");
 
-const TOOL_NAME = 'set_avatar';
+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');
+  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',
+    "Generate a custom avatar image from a text description. " +
+    "Saves the result as the assistant's avatar.",
+  category: "system",
   defaultRiskLevel: RiskLevel.Low,
 
   getDefinition(): ToolDefinition {
@@ -31,16 +34,21 @@ export const setAvatarTool: Tool = {
       name: TOOL_NAME,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           description: {
-            type: 'string',
+            type: "string",
             description:
-              'A text description of the desired avatar appearance, ' +
+              "A text description of the desired avatar appearance, " +
               'e.g. "a friendly purple cat with green eyes wearing a tiny hat".',
           },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are creating and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
+          },
         },
-        required: ['description'],
+        required: ["description"],
       },
     };
   },
@@ -50,9 +58,10 @@ export const setAvatarTool: Tool = {
     _context: ToolContext,
   ): Promise<ToolExecutionResult> {
     const description = input.description;
-    if (typeof description !== 'string' || description.trim() === '') {
+    if (typeof description !== "string" || description.trim() === "") {
       return {
-        content: 'Error: description is required and must be a non-empty string.',
+        content:
+          "Error: description is required and must be a non-empty string.",
         isError: true,
       };
     }
@@ -61,36 +70,40 @@ export const setAvatarTool: Tool = {
     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.',
+        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');
+      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).';
+        "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',
+        mode: "generate",
         model: config.imageGenModel,
       });
 
       if (result.images.length === 0) {
         return {
-          content: 'Error: Gemini returned no image data. Please try again.',
+          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 pngBuffer = Buffer.from(image.dataBase64, "base64");
 
       const avatarPath = getAvatarPath();
       const avatarDir = dirname(avatarPath);
@@ -98,17 +111,17 @@ export const setAvatarTool: Tool = {
       mkdirSync(avatarDir, { recursive: true });
       writeFileSync(avatarPath, pngBuffer);
 
-      log.info({ avatarPath }, 'Avatar saved successfully');
+      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.',
+        content: "Avatar updated! Your new avatar will appear shortly.",
         isError: false,
       };
     } catch (error) {
       const message = mapGeminiError(error);
-      log.error({ error: message }, 'Avatar generation failed');
+      log.error({ error: message }, "Avatar generation failed");
 
       return {
         content: `Avatar generation failed: ${message}`,

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

@@ -1,23 +1,23 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+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',
+  "Voice",
+  "Connect",
+  "Trust",
+  "Model",
+  "Scheduling",
 ] as const;
 
 type SettingsTab = (typeof SETTINGS_TABS)[number];
 
 export class NavigateSettingsTabTool implements Tool {
-  name = 'navigate_settings_tab';
+  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';
+    "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 {
@@ -25,31 +25,41 @@ export class NavigateSettingsTabTool implements Tool {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           tab: {
-            type: 'string',
+            type: "string",
             enum: [...SETTINGS_TABS],
-            description: 'The settings tab to navigate to',
+            description: "The settings tab to navigate to",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are navigating to and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['tab'],
+        required: ["tab"],
       },
     };
   }
 
-  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  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(', ')}`,
+        content: `Error: unknown tab "${tab}". Valid tabs: ${SETTINGS_TABS.join(
+          ", ",
+        )}`,
         isError: true,
       };
     }
 
     if (context.sendToClient) {
       context.sendToClient({
-        type: 'navigate_settings',
+        type: "navigate_settings",
         tab,
       });
     }

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

@@ -1,17 +1,17 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+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.',
+    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.',
+    url: "x-apple.systempreferences:com.apple.preference.security?Privacy_SpeechRecognition",
+    label: "Speech Recognition privacy",
+    instruction: "Please toggle Vellum Assistant on.",
   },
 } as const;
 
@@ -20,11 +20,11 @@ type PaneName = keyof typeof PANES;
 const VALID_PANES = Object.keys(PANES) as PaneName[];
 
 export class OpenSystemSettingsTool implements Tool {
-  name = 'open_system_settings';
+  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';
+    "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 {
@@ -32,24 +32,34 @@ export class OpenSystemSettingsTool implements Tool {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           pane: {
-            type: 'string',
+            type: "string",
             enum: [...VALID_PANES],
-            description: 'The System Settings pane to open',
+            description: "The System Settings pane to open",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are opening and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['pane'],
+        required: ["pane"],
       },
     };
   }
 
-  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  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(', ')}`,
+        content: `Error: unknown pane "${pane}". Valid panes: ${VALID_PANES.join(
+          ", ",
+        )}`,
         isError: true,
       };
     }
@@ -60,7 +70,7 @@ export class OpenSystemSettingsTool implements Tool {
     // opens System Settings directly without a browser confirmation dialog.
     if (context.sendToClient) {
       context.sendToClient({
-        type: 'open_url',
+        type: "open_url",
         url: meta.url,
       });
     }

package/src/tools/system/request-permission.ts

@@ -1,52 +1,61 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import { RiskLevel } from "../../permissions/types.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import { registerTool } from "../registry.js";
+import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const PERMISSION_TYPES = [
-  'full_disk_access',
-  'accessibility',
-  'screen_recording',
-  'calendar',
-  'contacts',
-  'photos',
-  'location',
-  'microphone',
-  'camera',
+  "full_disk_access",
+  "accessibility",
+  "screen_recording",
+  "calendar",
+  "contacts",
+  "photos",
+  "location",
+  "microphone",
+  "camera",
 ] as const;
 
 type PermissionType = (typeof PERMISSION_TYPES)[number];
 
 const SETTINGS_URLS: Record<PermissionType, string> = {
-  full_disk_access: 'x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles',
-  accessibility: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility',
-  screen_recording: 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture',
-  calendar: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars',
-  contacts: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Contacts',
-  photos: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Photos',
-  location: 'x-apple.systempreferences:com.apple.preference.security?Privacy_LocationServices',
-  microphone: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone',
-  camera: 'x-apple.systempreferences:com.apple.preference.security?Privacy_Camera',
+  full_disk_access:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles",
+  accessibility:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
+  screen_recording:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
+  calendar:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars",
+  contacts:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Contacts",
+  photos:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Photos",
+  location:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_LocationServices",
+  microphone:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone",
+  camera:
+    "x-apple.systempreferences:com.apple.preference.security?Privacy_Camera",
 };
 
 const FRIENDLY_NAMES: Record<PermissionType, string> = {
-  full_disk_access: 'Full Disk Access',
-  accessibility: 'Accessibility',
-  screen_recording: 'Screen Recording',
-  calendar: 'Calendar',
-  contacts: 'Contacts',
-  photos: 'Photos',
-  location: 'Location Services',
-  microphone: 'Microphone',
-  camera: 'Camera',
+  full_disk_access: "Full Disk Access",
+  accessibility: "Accessibility",
+  screen_recording: "Screen Recording",
+  calendar: "Calendar",
+  contacts: "Contacts",
+  photos: "Photos",
+  location: "Location Services",
+  microphone: "Microphone",
+  camera: "Camera",
 };
 
 class RequestSystemPermissionTool implements Tool {
-  name = 'request_system_permission';
+  name = "request_system_permission";
   description =
-    'Ask the user to grant a macOS system permission (e.g. Full Disk Access) via System Settings. ' +
-    'Use this when a tool execution fails because of a TCC/permission error.';
-  category = 'system';
+    "Ask the user to grant a macOS system permission (e.g. Full Disk Access) via System Settings. " +
+    "Use this when a tool execution fails because of a TCC/permission error.";
+  category = "system";
   defaultRiskLevel = RiskLevel.High;
 
   getDefinition(): ToolDefinition {
@@ -54,28 +63,34 @@ class RequestSystemPermissionTool implements Tool {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           permission_type: {
-            type: 'string',
+            type: "string",
             enum: [...PERMISSION_TYPES],
-            description: 'The macOS system permission to request',
+            description: "The macOS system permission to request",
           },
           reason: {
-            type: 'string',
-            description: 'Short explanation of why this permission is needed (shown to the user)',
+            type: "string",
+            description:
+              "Short explanation of why this permission is needed (shown to the user)",
           },
         },
-        required: ['permission_type', 'reason'],
+        required: ["permission_type", "reason"],
       },
     };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  async execute(
+    input: Record<string, unknown>,
+    _context: ToolContext,
+  ): Promise<ToolExecutionResult> {
     const permType = input.permission_type as string;
     if (!PERMISSION_TYPES.includes(permType as PermissionType)) {
       return {
-        content: `Error: unknown permission type "${permType}". Valid types: ${PERMISSION_TYPES.join(', ')}`,
+        content: `Error: unknown permission type "${permType}". Valid types: ${PERMISSION_TYPES.join(
+          ", ",
+        )}`,
         isError: true,
       };
     }
@@ -89,7 +104,7 @@ class RequestSystemPermissionTool implements Tool {
         `Settings URL: ${settingsUrl}`,
         `If they approved, retry the original operation.`,
         `If they denied, acknowledge and suggest alternatives.`,
-      ].join('\n'),
+      ].join("\n"),
       isError: false,
     };
   }

package/src/tools/system/version.ts

@@ -1,25 +1,27 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import { RiskLevel } from "../../permissions/types.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import { registerTool } from "../registry.js";
+import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 function readPackageVersion(): string {
   try {
-    const pkgPath = join(import.meta.dir, '../../../package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
-    return pkg.version ?? 'unknown';
+    const pkgPath = join(import.meta.dir, "../../../package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+      version?: string;
+    };
+    return pkg.version ?? "unknown";
   } catch {
-    return 'unknown';
+    return "unknown";
   }
 }
 
 class VersionTool implements Tool {
-  name = 'version';
-  description = 'Return the current version of the Vellum assistant daemon.';
-  category = 'system';
+  name = "version";
+  description = "Return the current version of the Vellum assistant daemon.";
+  category = "system";
   defaultRiskLevel = RiskLevel.Low;
 
   getDefinition(): ToolDefinition {
@@ -27,14 +29,23 @@ class VersionTool implements Tool {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
-        properties: {},
+        type: "object",
+        properties: {
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of why you are checking the version, shown to the user as a status update. Use simple language a non-technical person would understand.",
+          },
+        },
         required: [],
       },
     };
   }
 
-  async execute(_input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  async execute(
+    _input: Record<string, unknown>,
+    _context: ToolContext,
+  ): Promise<ToolExecutionResult> {
     const version = readPackageVersion();
     return { content: `Vellum assistant version: ${version}`, isError: false };
   }