vellum 0.0.16 → 0.2.0

package/src/tools/swarm/delegate.ts

@@ -0,0 +1,182 @@
+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 { 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}: ${task.objective.slice(0, 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();
+}

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

@@ -0,0 +1,98 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+
+const PERMISSION_TYPES = [
+  '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',
+};
+
+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',
+};
+
+class RequestSystemPermissionTool implements Tool {
+  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';
+  defaultRiskLevel = RiskLevel.High;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          permission_type: {
+            type: 'string',
+            enum: [...PERMISSION_TYPES],
+            description: 'The macOS system permission to request',
+          },
+          reason: {
+            type: 'string',
+            description: 'Short explanation of why this permission is needed (shown to the user)',
+          },
+        },
+        required: ['permission_type', 'reason'],
+      },
+    };
+  }
+
+  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(', ')}`,
+        isError: true,
+      };
+    }
+
+    const friendly = FRIENDLY_NAMES[permType as PermissionType];
+    const settingsUrl = SETTINGS_URLS[permType as PermissionType];
+
+    return {
+      content: [
+        `The user has been asked to grant ${friendly}.`,
+        `Settings URL: ${settingsUrl}`,
+        `If they approved, retry the original operation.`,
+        `If they denied, acknowledge and suggest alternatives.`,
+      ].join('\n'),
+      isError: false,
+    };
+  }
+}
+
+registerTool(new RequestSystemPermissionTool());

package/src/tools/tasks/index.ts

@@ -0,0 +1,25 @@
+/**
+ * UX Terminology Glossary
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * "Task" (user-facing) — A work item in the Tasks panel (backed by the
+ *   `work_items` table). This is what users see, create, run, and track.
+ *   The user-facing surface is simply called "Tasks".
+ *
+ * "Task template" / "task definition" (internal) — A reusable template
+ *   saved from a conversation (backed by the `tasks` table). Templates
+ *   define the prompt pattern and input schema; each run of a template
+ *   produces a work item. The tools below (task_save, task_list, etc.)
+ *   operate on these internal templates.
+ *
+ * When writing user-facing copy, prefer "Tasks" (meaning the work queue)
+ * over "task list" or "saved tasks". Reserve "task template" for internal
+ * comments, logs, and developer-facing docs.
+ */
+
+export { taskSaveTool } from './task-save.js';
+export { taskRunTool } from './task-run.js';
+export { taskListTool } from './task-list.js';
+export { taskDeleteTool } from './task-delete.js';
+export { taskListShowTool } from './work-item-list.js';
+export { taskListAddTool } from './work-item-enqueue.js';

package/src/tools/tasks/task-delete.ts

@@ -0,0 +1,69 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { deleteTask, deleteTasks, getTask } from '../../tasks/task-store.js';
+
+const definition: ToolDefinition = {
+  name: 'task_delete',
+  description: 'Delete one or more task templates by ID. Also removes associated task runs and work items (Tasks).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      task_ids: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'One or more task IDs to delete.',
+      },
+    },
+    required: ['task_ids'],
+  },
+};
+
+class TaskDeleteTool implements Tool {
+  name = 'task_delete';
+  description = definition.description;
+  category = 'tasks';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const raw = input.task_ids;
+    if (!Array.isArray(raw) || raw.length === 0) {
+      return { content: 'Error: task_ids must be a non-empty array of task ID strings', isError: true };
+    }
+    const ids = raw.filter((v): v is string => typeof v === 'string' && v.trim().length > 0);
+    if (ids.length === 0) {
+      return { content: 'Error: task_ids must contain at least one non-empty string', isError: true };
+    }
+
+    try {
+      if (ids.length === 1) {
+        const task = getTask(ids[0]);
+        const deleted = deleteTask(ids[0]);
+        if (!deleted) {
+          return { content: `No task found with ID ${ids[0]}`, isError: true };
+        }
+        return { content: `Deleted task: ${task?.title ?? ids[0]}`, isError: false };
+      }
+
+      const titles = ids.map((id) => {
+        const t = getTask(id);
+        return t ? t.title : id;
+      });
+      const count = deleteTasks(ids);
+      if (count === 0) {
+        return { content: 'No matching tasks found to delete.', isError: true };
+      }
+      const lines = [`Deleted ${count} task(s):`, ...titles.map((t) => `- ${t}`)];
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+export const taskDeleteTool = new TaskDeleteTool();

package/src/tools/tasks/task-list.ts

@@ -0,0 +1,65 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { listTasks } from '../../tasks/task-store.js';
+
+const definition: ToolDefinition = {
+  name: 'task_list',
+  description: 'List saved task templates (reusable definitions). To see your active Tasks (work items), use task_list_show instead.',
+  input_schema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+class TaskListTool implements Tool {
+  name = 'task_list';
+  description = definition.description;
+  category = 'tasks';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(_input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    try {
+      const tasks = listTasks();
+
+      if (tasks.length === 0) {
+        return { content: 'No task templates found. Use task_save to create one from a conversation.\n\nTip: To see your active Tasks (work items in the queue), use the task_list_show tool.', isError: false };
+      }
+
+      const lines = [`Found ${tasks.length} task template(s):`, ''];
+
+      for (const task of tasks) {
+        const requiredTools: string[] = task.requiredTools ? JSON.parse(task.requiredTools) : [];
+        const createdAt = new Date(task.createdAt).toISOString();
+
+        lines.push(`- ${task.title}`);
+        lines.push(`    ID: ${task.id}`);
+        lines.push(`    Status: ${task.status}`);
+        lines.push(`    Created: ${createdAt}`);
+        if (requiredTools.length > 0) {
+          lines.push(`    Required tools: ${requiredTools.join(', ')}`);
+        }
+        if (task.inputSchema) {
+          const schema = JSON.parse(task.inputSchema) as { properties?: Record<string, unknown> };
+          if (schema.properties) {
+            lines.push(`    Inputs: ${Object.keys(schema.properties).join(', ')}`);
+          }
+        }
+        lines.push('');
+      }
+
+      lines.push('Tip: To see your active Tasks (work items in the queue), use the task_list_show tool.');
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+export const taskListTool = new TaskListTool();

package/src/tools/tasks/task-run.ts

@@ -0,0 +1,125 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { getTask, listTasks } from '../../tasks/task-store.js';
+import { renderTemplate } from '../../tasks/task-runner.js';
+
+const definition: ToolDefinition = {
+  name: 'task_run',
+  description:
+    'Run a task template. Resolves the template by name (fuzzy match) or ID, renders it with the provided inputs, and returns the rendered prompt for execution as a Task (work item).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      task_name: {
+        type: 'string',
+        description: 'Fuzzy match a task template by name (case-insensitive substring match)',
+      },
+      task_id: {
+        type: 'string',
+        description: 'Exact match a task template by ID',
+      },
+      inputs: {
+        type: 'object',
+        description: 'Values for template placeholders (e.g. {"file_path": "/tmp/foo.txt", "url": "https://example.com"})',
+        additionalProperties: { type: 'string' },
+      },
+    },
+  },
+};
+
+class TaskRunTool implements Tool {
+  name = 'task_run';
+  description = definition.description;
+  category = 'tasks';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const taskName = input.task_name as string | undefined;
+    const taskId = input.task_id as string | undefined;
+    const inputs = (input.inputs as Record<string, string> | undefined) ?? {};
+
+    if (!taskName && !taskId) {
+      return {
+        content: 'Error: At least one of task_name or task_id must be provided',
+        isError: true,
+      };
+    }
+
+    try {
+      // Resolve the task
+      let task;
+
+      if (taskId) {
+        task = getTask(taskId);
+        if (!task) {
+          return { content: `Error: No task found with ID "${taskId}"`, isError: true };
+        }
+      } else if (taskName) {
+        const allTasks = listTasks();
+        const needle = taskName.toLowerCase();
+
+        // Case-insensitive substring match
+        task = allTasks.find((t) => t.title.toLowerCase().includes(needle));
+
+        if (!task) {
+          if (allTasks.length === 0) {
+            return { content: 'Error: No task templates found. Use task_save to create one first.', isError: true };
+          }
+          const available = allTasks.map((t) => `  - "${t.title}" (${t.id})`).join('\n');
+          return {
+            content: `Error: No task template matching "${taskName}" found. Available templates:\n${available}`,
+            isError: true,
+          };
+        }
+      }
+
+      if (!task) {
+        return { content: 'Error: Could not resolve task template', isError: true };
+      }
+
+      // Check if required inputs are provided
+      if (task.inputSchema) {
+        const schema = JSON.parse(task.inputSchema) as { properties?: Record<string, unknown> };
+        if (schema.properties) {
+          const requiredKeys = Object.keys(schema.properties);
+          const missingKeys = requiredKeys.filter((k) => !(k in inputs));
+          if (missingKeys.length > 0) {
+            return {
+              content: `Error: Missing required inputs: ${missingKeys.join(', ')}. Provide them in the "inputs" parameter.`,
+              isError: true,
+            };
+          }
+        }
+      }
+
+      // Render the template
+      const rendered = renderTemplate(task.template, inputs);
+
+      const requiredTools: string[] = task.requiredTools ? JSON.parse(task.requiredTools) : [];
+
+      const lines = [
+        `Template "${task.title}" resolved and rendered.`,
+        ``,
+        `I'll now execute the following:`,
+        ``,
+        rendered,
+      ];
+
+      if (requiredTools.length > 0) {
+        lines.push('', `Required tools: ${requiredTools.join(', ')}`);
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+export const taskRunTool = new TaskRunTool();

package/src/tools/tasks/task-save.ts

@@ -0,0 +1,79 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { compileTaskFromConversation, saveCompiledTask } from '../../tasks/task-compiler.js';
+
+const definition: ToolDefinition = {
+  name: 'task_save',
+  description:
+    'Save the current conversation as a reusable task template (definition). This is NOT for adding items to the user\'s task queue — use task_list_add for that. task_save extracts the conversation pattern into a reusable definition with placeholders that can be run later with different inputs.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      conversation_id: {
+        type: 'string',
+        description: 'The conversation to capture as a task template. If omitted, uses the current conversation.',
+      },
+      title: {
+        type: 'string',
+        description: 'Optional override for the auto-generated task title',
+      },
+    },
+    required: [],
+  },
+};
+
+class TaskSaveTool implements Tool {
+  name = 'task_save';
+  description = definition.description;
+  category = 'tasks';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const conversationId = (input.conversation_id as string | undefined) || context.conversationId;
+    if (!conversationId || typeof conversationId !== 'string' || conversationId.trim().length === 0) {
+      return { content: 'Error: conversation_id is required and must be a non-empty string', isError: true };
+    }
+
+    const titleOverride = input.title as string | undefined;
+
+    try {
+      const compiled = compileTaskFromConversation(conversationId);
+
+      if (titleOverride && typeof titleOverride === 'string' && titleOverride.trim().length > 0) {
+        compiled.title = titleOverride.trim();
+      }
+
+      const task = saveCompiledTask(compiled, conversationId);
+
+      const lines = [
+        `Task saved successfully.`,
+        `  ID: ${task.id}`,
+        `  Title: ${task.title}`,
+        `  Template: ${task.template}`,
+      ];
+
+      if (compiled.requiredTools.length > 0) {
+        lines.push(`  Required tools: ${compiled.requiredTools.join(', ')}`);
+      }
+
+      if (compiled.inputSchema) {
+        const props = (compiled.inputSchema as Record<string, unknown>).properties as Record<string, unknown> | undefined;
+        if (props) {
+          lines.push(`  Input placeholders: ${Object.keys(props).join(', ')}`);
+        }
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error: ${msg}`, isError: true };
+    }
+  }
+}
+
+export const taskSaveTool = new TaskSaveTool();