@vellumai/assistant 0.3.0

package/src/tools/skills/skill-tool-factory.ts

@@ -0,0 +1,64 @@
+import type { ExecutionTarget, Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { SkillToolEntry } from '../../config/skills.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { RiskLevel } from '../../permissions/types.js';
+import { runSkillToolScript } from './skill-script-runner.js';
+
+const riskMap: Record<SkillToolEntry['risk'], RiskLevel> = {
+  low: RiskLevel.Low,
+  medium: RiskLevel.Medium,
+  high: RiskLevel.High,
+};
+
+/**
+ * Create a runtime Tool object from a manifest entry.
+ * Maps SkillToolEntry metadata to the Tool interface and routes execution
+ * through the skill script runner.
+ */
+export function createSkillTool(
+  entry: SkillToolEntry,
+  skillId: string,
+  skillDir: string,
+  versionHash: string,
+  bundled?: boolean,
+): Tool {
+  return {
+    name: entry.name,
+    description: entry.description,
+    category: entry.category,
+    defaultRiskLevel: riskMap[entry.risk],
+    origin: 'skill',
+    ownerSkillId: skillId,
+    executionTarget: entry.execution_target as ExecutionTarget,
+    ownerSkillVersionHash: versionHash,
+    ownerSkillBundled: bundled,
+
+    getDefinition(): ToolDefinition {
+      return {
+        name: entry.name,
+        description: entry.description,
+        input_schema: entry.input_schema as ToolDefinition['input_schema'],
+      };
+    },
+
+    async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+      return runSkillToolScript(skillDir, entry.executor, input, context, {
+        target: entry.execution_target,
+        expectedSkillVersionHash: versionHash,
+      });
+    },
+  };
+}
+
+/**
+ * Create runtime Tool objects from all entries in a manifest.
+ */
+export function createSkillToolsFromManifest(
+  entries: SkillToolEntry[],
+  skillId: string,
+  skillDir: string,
+  versionHash: string,
+  bundled?: boolean,
+): Tool[] {
+  return entries.map(entry => createSkillTool(entry, skillId, skillDir, versionHash, bundled));
+}

package/src/tools/skills/vellum-catalog.ts

@@ -0,0 +1,217 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { RiskLevel } from '../../permissions/types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { createManagedSkill } from '../../skills/managed-store.js';
+import { getLogger } from '../../util/logger.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+
+const log = getLogger('vellum-skills-catalog');
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+function getVellumSkillsDir(): string {
+  return join(import.meta.dir, '..', '..', 'config', 'vellum-skills');
+}
+
+interface CatalogEntry {
+  id: string;
+  name: string;
+  description: string;
+  emoji?: string;
+  includes?: string[];
+}
+
+function parseCatalogEntry(directory: string): CatalogEntry | null {
+  const skillFilePath = join(directory, 'SKILL.md');
+  if (!existsSync(skillFilePath)) return null;
+
+  try {
+    const stat = statSync(skillFilePath);
+    if (!stat.isFile()) return null;
+
+    const content = readFileSync(skillFilePath, 'utf-8');
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) return null;
+
+    const fields: Record<string, string> = {};
+    for (const line of match[1].split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const separatorIndex = trimmed.indexOf(':');
+      if (separatorIndex === -1) continue;
+
+      const key = trimmed.slice(0, separatorIndex).trim();
+      let value = trimmed.slice(separatorIndex + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      fields[key] = value;
+    }
+
+    const name = fields.name?.trim();
+    const description = fields.description?.trim();
+    if (!name || !description) return null;
+
+    let emoji: string | undefined;
+    const metadataRaw = fields.metadata?.trim();
+    if (metadataRaw) {
+      try {
+        const parsed = JSON.parse(metadataRaw);
+        if (parsed?.vellum?.emoji) {
+          emoji = parsed.vellum.emoji as string;
+        }
+      } catch {
+        // ignore malformed metadata
+      }
+    }
+
+    let includes: string[] | undefined;
+    const includesRaw = fields.includes?.trim();
+    if (includesRaw) {
+      try {
+        const parsed = JSON.parse(includesRaw);
+        if (Array.isArray(parsed) && parsed.every((item: unknown) => typeof item === 'string')) {
+          const filtered = (parsed as string[]).map((s) => s.trim()).filter((s) => s.length > 0);
+          if (filtered.length > 0) includes = filtered;
+        }
+      } catch {
+        // ignore malformed includes
+      }
+    }
+
+    return { id: basename(directory), name, description, emoji, includes };
+  } catch (err) {
+    log.warn({ err, directory }, 'Failed to read catalog entry');
+    return null;
+  }
+}
+
+function listCatalogEntries(): CatalogEntry[] {
+  const catalogDir = getVellumSkillsDir();
+  if (!existsSync(catalogDir)) return [];
+
+  const entries: CatalogEntry[] = [];
+  try {
+    const dirEntries = readdirSync(catalogDir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+      if (!entry.isDirectory()) continue;
+      const parsed = parseCatalogEntry(join(catalogDir, entry.name));
+      if (parsed) entries.push(parsed);
+    }
+  } catch (err) {
+    log.warn({ err, catalogDir }, 'Failed to list catalog entries');
+  }
+
+  return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+class VellumSkillsCatalogTool implements Tool {
+  name = 'vellum_skills_catalog';
+  description = 'List and install Vellum-provided skills from the first-party catalog';
+  category = 'skills';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'install'],
+            description: 'The operation to perform. "list" shows available skills; "install" copies a skill to managed skills.',
+          },
+          skill_id: {
+            type: 'string',
+            description: 'The skill ID to install (required for install action).',
+          },
+          overwrite: {
+            type: 'boolean',
+            description: 'Whether to overwrite if the skill is already installed (default: false).',
+          },
+        },
+        required: ['action'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const action = input.action as string;
+
+    switch (action) {
+      case 'list': {
+        const entries = listCatalogEntries();
+        if (entries.length === 0) {
+          return { content: 'No Vellum-provided skills available in the catalog.', isError: false };
+        }
+        return { content: JSON.stringify(entries, null, 2), isError: false };
+      }
+
+      case 'install': {
+        const skillId = input.skill_id;
+        if (typeof skillId !== 'string' || !skillId.trim()) {
+          return { content: 'Error: skill_id is required for install action', isError: true };
+        }
+
+        const catalogDir = getVellumSkillsDir();
+        const skillDir = join(catalogDir, skillId.trim());
+        const skillFilePath = join(skillDir, 'SKILL.md');
+
+        if (!existsSync(skillFilePath)) {
+          const available = listCatalogEntries().map((e) => e.id);
+          return {
+            content: `Error: skill "${skillId}" not found in the Vellum catalog. Available: ${available.join(', ') || 'none'}`,
+            isError: true,
+          };
+        }
+
+        const content = readFileSync(skillFilePath, 'utf-8');
+        const match = content.match(FRONTMATTER_REGEX);
+        if (!match) {
+          return { content: `Error: skill "${skillId}" has invalid SKILL.md (missing frontmatter)`, isError: true };
+        }
+
+        const entry = parseCatalogEntry(skillDir);
+        if (!entry) {
+          return { content: `Error: skill "${skillId}" has invalid SKILL.md`, isError: true };
+        }
+
+        const bodyMarkdown = content.slice(match[0].length);
+
+        const result = createManagedSkill({
+          id: entry.id,
+          name: entry.name,
+          description: entry.description,
+          bodyMarkdown,
+          emoji: entry.emoji,
+          includes: entry.includes,
+          overwrite: input.overwrite === true,
+          addToIndex: true,
+        });
+
+        if (!result.created) {
+          return { content: `Error: ${result.error}`, isError: true };
+        }
+
+        return {
+          content: JSON.stringify({
+            installed: true,
+            skill_id: entry.id,
+            name: entry.name,
+            path: result.path,
+          }),
+          isError: false,
+        };
+      }
+
+      default:
+        return { content: `Error: unknown action "${action}". Use "list" or "install".`, isError: true };
+    }
+  }
+}
+
+export const vellumSkillsCatalogTool: Tool = new VellumSkillsCatalogTool();

package/src/tools/subagent/abort.ts

@@ -0,0 +1,33 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getSubagentManager } from '../../subagent/index.js';
+
+export async function executeSubagentAbort(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const subagentId = input.subagent_id as string;
+  if (!subagentId) {
+    return { content: '"subagent_id" is required.', isError: true };
+  }
+
+  const manager = getSubagentManager();
+  const sendToClient = context.sendToClient as ((msg: unknown) => void) | undefined;
+  const aborted = manager.abort(
+    subagentId,
+    sendToClient as ((msg: unknown) => void) | undefined,
+    context.sessionId,
+    { suppressNotification: true },
+  );
+
+  if (!aborted) {
+    return {
+      content: `Could not abort subagent "${subagentId}". It may not exist or already be in a terminal state.`,
+      isError: true,
+    };
+  }
+
+  return {
+    content: JSON.stringify({ subagentId, status: 'aborted', message: 'Subagent aborted successfully.' }),
+    isError: false,
+  };
+}

package/src/tools/subagent/message.ts

@@ -0,0 +1,39 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getSubagentManager } from '../../subagent/index.js';
+
+export async function executeSubagentMessage(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const subagentId = input.subagent_id as string;
+  const content = input.content as string;
+
+  if (!subagentId || !content) {
+    return { content: 'Both "subagent_id" and "content" are required.', isError: true };
+  }
+
+  const manager = getSubagentManager();
+
+  // Ownership check: only the parent session can message a subagent.
+  const state = manager.getState(subagentId);
+  if (!state || state.config.parentSessionId !== context.sessionId) {
+    return {
+      content: `Could not send message to subagent "${subagentId}". It may not exist or be in a terminal state.`,
+      isError: true,
+    };
+  }
+
+  const sent = manager.sendMessage(subagentId, content);
+
+  if (!sent) {
+    return {
+      content: `Could not send message to subagent "${subagentId}". It may not exist or be in a terminal state.`,
+      isError: true,
+    };
+  }
+
+  return {
+    content: JSON.stringify({ subagentId, message: 'Message sent to subagent.' }),
+    isError: false,
+  };
+}

package/src/tools/subagent/read.ts

@@ -0,0 +1,67 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getSubagentManager, TERMINAL_STATUSES } from '../../subagent/index.js';
+import { getMessages } from '../../memory/conversation-store.js';
+
+export async function executeSubagentRead(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const subagentId = input.subagent_id as string;
+  if (!subagentId) {
+    return { content: '"subagent_id" is required.', isError: true };
+  }
+
+  const manager = getSubagentManager();
+  const state = manager.getState(subagentId);
+  if (!state) {
+    return { content: `No subagent found with ID "${subagentId}".`, isError: true };
+  }
+
+  // Ownership check: only the parent session can read a subagent's output.
+  if (state.config.parentSessionId !== context.sessionId) {
+    return { content: `No subagent found with ID "${subagentId}".`, isError: true };
+  }
+
+  if (!TERMINAL_STATUSES.has(state.status)) {
+    return {
+      content: `Subagent "${state.config.label}" is still ${state.status}. Wait for it to finish.`,
+      isError: false,
+    };
+  }
+
+  // Read the subagent's conversation messages from DB.
+  const dbMessages = getMessages(state.conversationId);
+  if (!dbMessages || dbMessages.length === 0) {
+    return { content: 'No messages found in subagent conversation.', isError: true };
+  }
+
+  // Extract assistant messages only — that's the subagent's output.
+  const output: string[] = [];
+  for (const msg of dbMessages) {
+    if (msg.role !== 'assistant') continue;
+    try {
+      const content = JSON.parse(msg.content);
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text' && typeof block.text === 'string') {
+            output.push(block.text);
+          }
+        }
+      } else if (typeof content === 'string') {
+        output.push(content);
+      }
+    } catch {
+      // Content might be plain text.
+      output.push(msg.content);
+    }
+  }
+
+  if (output.length === 0) {
+    return { content: 'Subagent produced no text output.', isError: false };
+  }
+
+  return {
+    content: output.join('\n\n'),
+    isError: false,
+  };
+}

package/src/tools/subagent/spawn.ts

@@ -0,0 +1,46 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getSubagentManager } from '../../subagent/index.js';
+
+export async function executeSubagentSpawn(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const label = input.label as string;
+  const objective = input.objective as string;
+  const extraContext = input.context as string | undefined;
+
+  if (!label || !objective) {
+    return { content: 'Both "label" and "objective" are required.', isError: true };
+  }
+
+  const manager = getSubagentManager();
+  const sendToClient = context.sendToClient as ((msg: { type: string; [key: string]: unknown }) => void) | undefined;
+  if (!sendToClient) {
+    return { content: 'No IPC client connected — cannot spawn subagent.', isError: true };
+  }
+
+  try {
+    const subagentId = await manager.spawn(
+      {
+        parentSessionId: context.sessionId,
+        label,
+        objective,
+        context: extraContext,
+      },
+      sendToClient as (msg: unknown) => void,
+    );
+
+    return {
+      content: JSON.stringify({
+        subagentId,
+        label,
+        status: 'pending',
+        message: `Subagent "${label}" spawned. You will be notified automatically when it completes or fails — do NOT poll subagent_status. Continue the conversation normally.`,
+      }),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Failed to spawn subagent: ${msg}`, isError: true };
+  }
+}

package/src/tools/subagent/status.ts

@@ -0,0 +1,45 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getSubagentManager } from '../../subagent/index.js';
+
+export async function executeSubagentStatus(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const subagentId = input.subagent_id as string | undefined;
+  const manager = getSubagentManager();
+
+  if (subagentId) {
+    const state = manager.getState(subagentId);
+    if (!state || state.config.parentSessionId !== context.sessionId) {
+      return { content: `No subagent found with ID "${subagentId}".`, isError: true };
+    }
+    return {
+      content: JSON.stringify({
+        subagentId: state.config.id,
+        label: state.config.label,
+        status: state.status,
+        error: state.error,
+        createdAt: state.createdAt,
+        startedAt: state.startedAt,
+        completedAt: state.completedAt,
+        usage: state.usage,
+      }),
+      isError: false,
+    };
+  }
+
+  // List all subagents for this parent session.
+  const children = manager.getChildrenOf(context.sessionId);
+  if (children.length === 0) {
+    return { content: 'No subagents found for this session.', isError: false };
+  }
+
+  const summary = children.map((s) => ({
+    subagentId: s.config.id,
+    label: s.config.label,
+    status: s.status,
+    error: s.error,
+  }));
+
+  return { content: JSON.stringify(summary), isError: false };
+}

package/src/tools/swarm/delegate.ts

@@ -0,0 +1,183 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { getConfig } from '../../config/loader.js';
+import { getLogger } from '../../util/logger.js';
+import { truncate } from '../../util/truncate.js';
+import { getFailoverProvider } from '../../providers/registry.js';
+import { resolveSwarmLimits } from '../../swarm/limits.js';
+import { generatePlan } from '../../swarm/router-planner.js';
+import { executeSwarm } from '../../swarm/orchestrator.js';
+import { createClaudeCodeBackend } from '../../swarm/backend-claude-code.js';
+
+const log = getLogger('swarm-delegate');
+
+/** Tracks active swarm sessions to prevent nested invocation per-session. */
+const activeSessions = new Set<string>();
+
+export const swarmDelegateTool: Tool = {
+  name: 'swarm_delegate',
+  description: 'Decompose a complex task into parallel specialist subtasks and execute them concurrently. Use this for multi-part tasks that benefit from parallel research, coding, and review.',
+  category: 'orchestration',
+  defaultRiskLevel: RiskLevel.Medium,
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: 'swarm_delegate',
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          objective: {
+            type: 'string',
+            description: 'The complex task to decompose and execute in parallel',
+          },
+          context: {
+            type: 'string',
+            description: 'Optional additional context about the task or codebase',
+          },
+          max_workers: {
+            type: 'number',
+            description: 'Maximum concurrent workers (1-6, default from config)',
+          },
+        },
+        required: ['objective'],
+      },
+    };
+  },
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const objective = input.objective as string;
+    const extraContext = input.context as string | undefined;
+    const maxWorkersOverride = input.max_workers as number | undefined;
+
+    // Check if swarm is enabled
+    const config = getConfig();
+    if (!config.swarm.enabled) {
+      return {
+        content: 'Swarm orchestration is disabled in config (swarm.enabled = false). Execute the task directly instead.',
+        isError: false,
+      };
+    }
+
+    // Early abort check
+    if (context.signal?.aborted) {
+      return { content: 'Cancelled', isError: true };
+    }
+
+    // Recursion guard — scoped to session so independent sessions are not blocked
+    const sessionKey = context.sessionId;
+    if (activeSessions.has(sessionKey)) {
+      return {
+        content: 'Error: A swarm is already executing in this session. Nested swarm invocation is not allowed.',
+        isError: true,
+      };
+    }
+
+    activeSessions.add(sessionKey);
+    try {
+      const limits = resolveSwarmLimits({
+        maxWorkers: maxWorkersOverride ?? config.swarm.maxWorkers,
+        maxTasks: config.swarm.maxTasks,
+        maxRetriesPerTask: config.swarm.maxRetriesPerTask,
+        workerTimeoutSec: config.swarm.workerTimeoutSec,
+      });
+
+      // Generate plan
+      context.onOutput?.('Planning task decomposition...\n');
+      const planProvider = getFailoverProvider(config.provider, config.providerOrder);
+      const plan = await generatePlan({
+        objective: extraContext ? `${objective}\n\nContext: ${extraContext}` : objective,
+        provider: planProvider,
+        model: config.swarm.plannerModel,
+        limits,
+      });
+
+      context.onOutput?.(`Plan: ${plan.tasks.length} tasks\n`);
+      for (const task of plan.tasks) {
+        context.onOutput?.(`  - [${task.role}] ${task.id}: ${truncate(task.objective, 80)}\n`);
+      }
+      context.onOutput?.('\nExecuting...\n');
+
+      if (context.signal?.aborted) {
+        return { content: 'Cancelled before execution', isError: true };
+      }
+
+      // Execute
+      const backend = createClaudeCodeBackend();
+      let synthesisProvider: typeof planProvider | undefined;
+      try {
+        synthesisProvider = getFailoverProvider(config.provider, config.providerOrder);
+      } catch {
+        // No provider available for synthesis — will use fallback
+      }
+
+      const summary = await executeSwarm({
+        plan,
+        limits,
+        backend,
+        workingDir: context.workingDir,
+        model: config.swarm.synthesizerModel,
+        synthesisProvider,
+        synthesisModel: config.swarm.synthesizerModel,
+        signal: context.signal,
+        onStatus: (event) => {
+          switch (event.kind) {
+            case 'task_started':
+              context.onOutput?.(`[START] ${event.taskId}\n`);
+              break;
+            case 'task_completed':
+              context.onOutput?.(`[DONE]  ${event.taskId}\n`);
+              break;
+            case 'task_failed':
+              context.onOutput?.(`[FAIL]  ${event.taskId}\n`);
+              break;
+            case 'task_blocked':
+              context.onOutput?.(`[BLOCK] ${event.taskId}\n`);
+              break;
+            case 'done':
+              context.onOutput?.(`\nSwarm completed.\n`);
+              break;
+          }
+        },
+      });
+
+      // Format result
+      const lines: string[] = [];
+      lines.push(summary.finalAnswer);
+      lines.push('');
+      lines.push(`---`);
+      lines.push(`Tasks: ${summary.stats.completed} completed, ${summary.stats.failed} failed, ${summary.stats.blocked} blocked`);
+      lines.push(`Duration: ${summary.stats.totalDurationMs}ms`);
+
+      if (summary.stats.failed > 0 || summary.stats.blocked > 0) {
+        lines.push('');
+        lines.push('### Issues');
+        for (const r of summary.results) {
+          if (r.status === 'failed') {
+            lines.push(`- **${r.taskId}** (failed): ${r.summary}`);
+          }
+        }
+      }
+
+      return {
+        content: lines.join('\n'),
+        isError: summary.stats.completed === 0,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err }, 'Swarm execution failed');
+      return {
+        content: `Swarm error: ${message}`,
+        isError: true,
+      };
+    } finally {
+      activeSessions.delete(sessionKey);
+    }
+  },
+};
+
+/** Clear all active sessions — only for testing. */
+export function _resetSwarmActive(): void {
+  activeSessions.clear();
+}