@vellumai/assistant 0.4.44 → 0.4.45

package/src/config/bundled-skills/sequences/tools/sequence-update.ts

@@ -0,0 +1,128 @@
+import {
+  exitEnrollment,
+  getEnrollment,
+  getSequence,
+  pauseEnrollment,
+  resumeEnrollment,
+  updateSequence,
+} from "../../../../sequence/store.js";
+import type {
+  SequenceStatus,
+  SequenceStep,
+} from "../../../../sequence/types.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { err, ok } from "./shared.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const id = input.id as string | undefined;
+  const enrollmentId = input.enrollment_id as string | undefined;
+  const enrollmentAction = input.enrollment_action as string | undefined;
+
+  // ── Enrollment-level lifecycle actions ──────────────────────────────
+  if (enrollmentId) {
+    if (!enrollmentAction)
+      return err(
+        "enrollment_action is required when enrollment_id is provided.",
+      );
+
+    try {
+      const enrollment = getEnrollment(enrollmentId);
+      if (!enrollment) return err(`Enrollment not found: ${enrollmentId}`);
+
+      switch (enrollmentAction) {
+        case "pause": {
+          if (enrollment.status !== "active")
+            return err(
+              `Enrollment is not active (status: ${enrollment.status}).`,
+            );
+          pauseEnrollment(enrollmentId);
+          return ok(
+            `Enrollment ${enrollmentId} paused. Resume it later to continue from step ${
+              enrollment.currentStep + 1
+            }.`,
+          );
+        }
+        case "resume": {
+          if (enrollment.status !== "paused")
+            return err(
+              `Enrollment is not paused (status: ${enrollment.status}).`,
+            );
+          const seq = enrollment.sequenceId
+            ? getSequence(enrollment.sequenceId)
+            : null;
+          if (seq && seq.status !== "active")
+            return err(
+              `Cannot resume enrollment — parent sequence "${seq.name}" is ${seq.status}. Resume the sequence first.`,
+            );
+          resumeEnrollment(enrollmentId);
+          return ok(`Enrollment ${enrollmentId} resumed.`);
+        }
+        case "cancel": {
+          if (
+            enrollment.status !== "active" &&
+            enrollment.status !== "paused"
+          ) {
+            return ok(
+              `Enrollment already in terminal state: ${enrollment.status}`,
+            );
+          }
+          exitEnrollment(enrollmentId, "cancelled");
+          return ok(`Enrollment for ${enrollment.contactEmail} cancelled.`);
+        }
+        default:
+          return err(
+            `Unknown enrollment_action: "${enrollmentAction}". Use "pause", "resume", or "cancel".`,
+          );
+      }
+    } catch (e) {
+      return err(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  // ── Sequence-level update ──────────────────────────────────────────
+  if (!id) return err("id is required.");
+
+  const name = input.name as string | undefined;
+  const description = input.description as string | undefined;
+  const status = input.status as SequenceStatus | undefined;
+  const exitOnReply = input.exit_on_reply as boolean | undefined;
+  const stepsRaw = input.steps as Array<Record<string, unknown>> | undefined;
+
+  try {
+    const steps = stepsRaw?.map(
+      (s, i): SequenceStep => ({
+        index: i,
+        delaySeconds: (s.delay_seconds as number) ?? 0,
+        subjectTemplate: (s.subject as string) ?? `Step ${i + 1}`,
+        bodyPrompt: (s.body_prompt as string) ?? "",
+        replyToThread: (s.reply_to_thread as boolean) ?? i > 0,
+        requireApproval: (s.require_approval as boolean) ?? false,
+      }),
+    );
+
+    if (steps !== undefined && steps.length === 0) {
+      return err(
+        "steps must not be empty. A sequence requires at least one step.",
+      );
+    }
+
+    const updated = updateSequence(id, {
+      name,
+      description,
+      status,
+      exitOnReply,
+      steps,
+    });
+    if (!updated) return err(`Sequence not found: ${id}`);
+
+    return ok(`Sequence updated: ${updated.name} (${updated.status})`);
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/sequences/tools/shared.ts

@@ -0,0 +1,9 @@
+import type { ToolExecutionResult } from "../../../../tools/types.js";
+
+export function ok(content: string): ToolExecutionResult {
+  return { content, isError: false };
+}
+
+export function err(message: string): ToolExecutionResult {
+  return { content: message, isError: true };
+}

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

@@ -0,0 +1,12 @@
+---
+name: settings
+description: Manage assistant voice, avatar, and system settings
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "\u2699\uFE0F"
+  vellum:
+    display-name: "Settings"
+    user-invocable: true
+---
+
+Tools for managing assistant settings: voice configuration (TTS voice, PTT activation key, wake word), avatar generation, system settings navigation, and in-app settings tab navigation.

package/src/config/bundled-skills/settings/TOOLS.json

@@ -0,0 +1,112 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "voice_config_update",
+      "description": "Update a voice configuration setting (TTS voice ID, PTT activation key, wake word enabled/keyword/timeout). Changes take effect immediately.",
+      "category": "system",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "setting": {
+            "type": "string",
+            "enum": [
+              "activation_key",
+              "wake_word_enabled",
+              "wake_word_keyword",
+              "wake_word_timeout",
+              "tts_voice_id"
+            ],
+            "description": "The voice setting to change"
+          },
+          "value": {
+            "description": "The new value for the setting (type depends on setting)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of what you are changing and why, shown to the user as a status update. Use simple language a non-technical person would understand."
+          }
+        }
+      },
+      "executor": "tools/voice-config-update.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "set_avatar",
+      "description": "Generate a custom avatar image from a text description. Saves the result as the assistant's avatar.",
+      "category": "system",
+      "risk": "low",
+      "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\"."
+          },
+          "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"]
+      },
+      "executor": "tools/set-avatar.ts",
+      "execution_target": "host"
+    },
+    {
+      "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",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "pane": {
+            "type": "string",
+            "enum": ["microphone", "speech_recognition"],
+            "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"]
+      },
+      "executor": "tools/open-system-settings.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "navigate_settings_tab",
+      "description": "Open the Vellum settings panel to a specific tab (e.g. General, Channels, Voice). Use this when the user needs to review or adjust settings visually.",
+      "category": "system",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "tab": {
+            "type": "string",
+            "enum": [
+              "General",
+              "Channels",
+              "Models & Services",
+              "Voice",
+              "Permissions & Privacy",
+              "Contacts",
+              "Developer"
+            ],
+            "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"]
+      },
+      "executor": "tools/navigate-settings-tab.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.ts

@@ -0,0 +1,43 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+const SETTINGS_TABS = [
+  "General",
+  "Channels",
+  "Models & Services",
+  "Voice",
+  "Permissions & Privacy",
+  "Contacts",
+  "Developer",
+] as const;
+
+type SettingsTab = (typeof SETTINGS_TABS)[number];
+
+export async function run(
+  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,
+  };
+}

package/src/config/bundled-skills/settings/tools/open-system-settings.ts

@@ -0,0 +1,52 @@
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/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 async function run(
+  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 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,
+  };
+}

package/src/config/bundled-skills/{computer-use/tools/computer-use-right-click.ts → settings/tools/set-avatar.ts}

@@ -1,4 +1,4 @@
-import { forwardComputerUseProxyTool } from "../../../../tools/computer-use/skill-proxy-bridge.js";
+import { setAvatarTool } from "../../../../tools/system/avatar-generator.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -8,9 +8,5 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return forwardComputerUseProxyTool(
-    "computer_use_right_click",
-    input,
-    context,
-  );
+  return setAvatarTool.execute(input, context);
 }

package/src/{tools/system/voice-config.ts → config/bundled-skills/settings/tools/voice-config-update.ts}

@@ -3,11 +3,12 @@ import {
   loadRawConfig,
   saveRawConfig,
   setNestedValue,
-} from "../../config/loader.js";
-import { normalizeActivationKey } from "../../daemon/handlers/config-voice.js";
-import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+} from "../../../../config/loader.js";
+import { normalizeActivationKey } from "../../../../daemon/handlers/config-voice.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
 
 /**
  * Valid voice config settings and their UserDefaults key mappings.
@@ -38,6 +39,14 @@ const VALID_SETTINGS = Object.keys(VOICE_SETTINGS) as VoiceSettingName[];
 
 const VALID_TIMEOUTS = [5, 10, 15, 30, 60];
 
+const FRIENDLY_NAMES: Record<VoiceSettingName, string> = {
+  activation_key: "PTT activation key",
+  wake_word_enabled: "Wake word",
+  wake_word_keyword: "Wake word keyword",
+  wake_word_timeout: "Wake word timeout",
+  tts_voice_id: "ElevenLabs voice",
+};
+
 function validateSetting(
   setting: string,
   value: unknown,
@@ -61,7 +70,6 @@ function validateSetting(
           error: "activation_key must be a non-empty string",
         };
       }
-      // Use the canonical normalizer from config-voice handler
       const result = normalizeActivationKey(value);
       if (!result.ok) {
         return { ok: false, error: result.reason };
@@ -121,104 +129,59 @@ function validateSetting(
   }
 }
 
-const FRIENDLY_NAMES: Record<VoiceSettingName, string> = {
-  activation_key: "PTT activation key",
-  wake_word_enabled: "Wake word",
-  wake_word_keyword: "Wake word keyword",
-  wake_word_timeout: "Wake word timeout",
-  tts_voice_id: "ElevenLabs voice",
-};
-
-export class VoiceConfigUpdateTool implements Tool {
-  name = "voice_config_update";
-  description =
-    "Update a voice configuration setting (TTS voice ID, PTT activation key, wake word enabled/keyword/timeout). " +
-    "Changes take effect immediately via IPC broadcast to the desktop client.";
-  category = "system";
-  defaultRiskLevel = RiskLevel.Low;
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const setting = input.setting as string | undefined;
+  const value = input.value;
 
-  getDefinition(): ToolDefinition {
+  if (!setting) {
     return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: "object",
-        properties: {
-          setting: {
-            type: "string",
-            enum: [...VALID_SETTINGS],
-            description: "The voice setting to change",
-          },
-          value: {
-            description:
-              "The new value for the setting (type depends on setting)",
-          },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are changing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
-        },
-      },
+      content: `Error: "setting" is required. Valid settings: ${VALID_SETTINGS.join(
+        ", ",
+      )}`,
+      isError: true,
     };
   }
 
-  async execute(
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolExecutionResult> {
-    const setting = input.setting as string | undefined;
-    const value = input.value;
-
-    if (!setting) {
-      return {
-        content: `Error: "setting" is required. Valid settings: ${VALID_SETTINGS.join(
-          ", ",
-        )}`,
-        isError: true,
-      };
-    }
-
-    if (value === undefined) {
-      return {
-        content: `Error: "value" is required for setting "${setting}".`,
-        isError: true,
-      };
-    }
-
-    const validation = validateSetting(setting, value);
-    if (!validation.ok) {
-      return { content: `Error: ${validation.error}`, isError: true };
-    }
+  if (value === undefined) {
+    return {
+      content: `Error: "value" is required for setting "${setting}".`,
+      isError: true,
+    };
+  }
 
-    const meta = VOICE_SETTINGS[setting as VoiceSettingName];
-    const friendlyName = FRIENDLY_NAMES[setting as VoiceSettingName];
+  const validation = validateSetting(setting, value);
+  if (!validation.ok) {
+    return { content: `Error: ${validation.error}`, isError: true };
+  }
 
-    // Send client_settings_update IPC to write to UserDefaults
-    if (context.sendToClient) {
-      context.sendToClient({
-        type: "client_settings_update",
-        key: meta.userDefaultsKey,
-        value: validation.coerced,
-      });
-    }
+  const meta = VOICE_SETTINGS[setting as VoiceSettingName];
+  const friendlyName = FRIENDLY_NAMES[setting as VoiceSettingName];
 
-    // For tts_voice_id, also persist to the config file (elevenlabs.voiceId)
-    // so phone calls and other consumers pick it up.
-    if (setting === "tts_voice_id") {
-      const raw = loadRawConfig();
-      setNestedValue(raw, "elevenlabs.voiceId", validation.coerced);
-      saveRawConfig(raw);
-      invalidateConfigCache();
-    }
+  // Send client_settings_update message to write to UserDefaults
+  if (context.sendToClient) {
+    context.sendToClient({
+      type: "client_settings_update",
+      key: meta.userDefaultsKey,
+      value: validation.coerced,
+    });
+  }
 
-    return {
-      content: `${friendlyName} updated to ${JSON.stringify(
-        validation.coerced,
-      )}. The change has been broadcast to the desktop client.`,
-      isError: false,
-    };
+  // For tts_voice_id, also persist to the config file (elevenlabs.voiceId)
+  // so phone calls and other consumers pick it up.
+  if (setting === "tts_voice_id") {
+    const raw = loadRawConfig();
+    setNestedValue(raw, "elevenlabs.voiceId", validation.coerced);
+    saveRawConfig(raw);
+    invalidateConfigCache();
   }
-}
 
-export const voiceConfigUpdateTool = new VoiceConfigUpdateTool();
+  return {
+    content: `${friendlyName} updated to ${JSON.stringify(
+      validation.coerced,
+    )}. The change has been broadcast to the desktop client.`,
+    isError: false,
+  };
+}

package/src/config/bundled-skills/skill-management/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: skill-management
+description: Create and delete custom managed skills
+metadata:
+  vellum:
+    emoji: "\U0001F9E9"
+    display-name: "Skill Management"
+    user-invocable: true
+---
+
+Manage the lifecycle of custom managed skills in `~/.vellum/workspace/skills`.
+
+## Capabilities
+
+- **Scaffold** a new managed skill with YAML frontmatter and markdown body
+- **Delete** an existing managed skill and remove it from the SKILLS.md index
+
+Skills created via `scaffold_managed_skill` become available for `skill_load` immediately.

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -0,0 +1,90 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "scaffold_managed_skill",
+      "description": "Create or update a managed skill in ~/.vellum/workspace/skills. The skill becomes available for skill_load immediately.",
+      "category": "skills",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "skill_id": {
+            "type": "string",
+            "description": "Unique identifier for the skill (lowercase slug, e.g. \"my-skill\")."
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable name for the skill."
+          },
+          "description": {
+            "type": "string",
+            "description": "Short description of what the skill does."
+          },
+          "body_markdown": {
+            "type": "string",
+            "description": "The full skill body in markdown — instructions, prompts, templates, etc."
+          },
+          "emoji": {
+            "type": "string",
+            "description": "Optional emoji icon for the skill."
+          },
+          "user_invocable": {
+            "type": "boolean",
+            "description": "Whether users can invoke this skill directly (default: true)."
+          },
+          "disable_model_invocation": {
+            "type": "boolean",
+            "description": "Whether to prevent the model from auto-invoking this skill (default: false)."
+          },
+          "overwrite": {
+            "type": "boolean",
+            "description": "Whether to overwrite an existing skill with the same ID (default: false)."
+          },
+          "add_to_index": {
+            "type": "boolean",
+            "description": "Whether to add the skill to SKILLS.md index (default: true)."
+          },
+          "includes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Optional list of child skill IDs that this skill includes (metadata only, no auto-activation)."
+          },
+          "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": ["skill_id", "name", "description", "body_markdown"]
+      },
+      "executor": "tools/scaffold-managed.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "delete_managed_skill",
+      "description": "Delete a managed skill from ~/.vellum/workspace/skills and remove it from the SKILLS.md index.",
+      "category": "skills",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "skill_id": {
+            "type": "string",
+            "description": "The ID of the managed skill to delete."
+          },
+          "remove_from_index": {
+            "type": "boolean",
+            "description": "Whether to remove the skill from SKILLS.md index (default: true)."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of what you are deleting and why, shown to the user as a status update. Use simple language a non-technical person would understand."
+          }
+        },
+        "required": ["skill_id"]
+      },
+      "executor": "tools/delete-managed.ts",
+      "execution_target": "host"
+    }
+  ]
+}