vellum 0.2.1 → 0.2.2

package/src/tools/tasks/work-item-enqueue.ts

@@ -1,8 +1,7 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { getTask, listTasks, createTask } from '../../tasks/task-store.js';
-import { createWorkItem, findActiveWorkItemsByTitle, updateWorkItem, identifyEntityById, buildWorkItemMismatchError } from '../../work-items/work-item-store.js';
+import { createWorkItemWithPermissions, findActiveWorkItemsByTitle, updateWorkItem, identifyEntityById, buildWorkItemMismatchError } from '../../work-items/work-item-store.js';
+import { sanitizeToolList } from '../../tasks/tool-sanitizer.js';
 import { getLogger } from '../../util/logger.js';
 
 const log = getLogger('task-list-add');
@@ -13,237 +12,114 @@ const PRIORITY_LABELS: Record<number, string> = {
   2: 'low',
 };
 
-const definition: ToolDefinition = {
-  name: 'task_list_add',
-  description:
-    'Add a task to the user\'s Task Queue. Use this when the user says "add to my tasks", "add to my queue", "put this on my task list", "track this task", or any variation of adding a one-off item they want to remember or work on. You can provide just a title for ad-hoc items, or reference an existing task definition by name or ID. Do NOT use schedule_create or reminder for simple "add to tasks" requests — those are for timed/recurring automation only.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      task_id: {
-        type: 'string',
-        description: 'ID of an existing task definition to enqueue. Provide this, task_name, or just title.',
-      },
-      task_name: {
-        type: 'string',
-        description:
-          'Title/name of an existing task definition to search for (case-insensitive substring match). Provide this, task_id, or just title.',
-      },
-      title: {
-        type: 'string',
-        description:
-          'Title for the work item. When provided WITHOUT task_id or task_name, creates an ad-hoc work item directly (a lightweight task template is auto-created behind the scenes). When provided WITH task_id or task_name, overrides the task definition title.',
-      },
-      notes: {
-        type: 'string',
-        description: 'Notes to attach to the work item.',
-      },
-      priority_tier: {
-        type: 'number',
-        description: '0 = high, 1 = medium (default), 2 = low.',
-      },
-      sort_index: {
-        type: 'number',
-        description: 'Manual sort order within the priority tier.',
-      },
-      if_exists: {
-        type: 'string',
-        enum: ['create_duplicate', 'reuse_existing', 'update_existing'],
-        description:
-          'What to do if an active work item with the same title already exists. Defaults to "reuse_existing".',
-      },
-    },
-  },
-};
-
-class TaskListAddTool implements Tool {
-  name = 'task_list_add';
-  description = definition.description;
-  category = 'tasks';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+function handleDuplicate(
+  title: string,
+  ifExists: string,
+  input: Record<string, unknown>,
+): ToolExecutionResult | null {
+  const existing = findActiveWorkItemsByTitle(title);
+  if (existing.length === 0) return null;
+
+  const match = existing[0];
+  log.info({ title, existingId: match.id, ifExists }, 'task_list_add: duplicate detected');
+
+  if (ifExists === 'reuse_existing') {
+    log.info({ title, existingId: match.id }, 'task_list_add: reused existing item');
+    return {
+      content: `Task "${match.title}" already exists in the queue (ID: ${match.id}, status: ${match.status}). Use task_list_update to modify it.`,
+      isError: false,
+    };
   }
 
-  /**
-   * Check for an existing active work item with the same title and handle
-   * according to the if_exists strategy. Returns a result if a duplicate was
-   * found and handled, or null if no duplicate exists (caller should proceed).
-   */
-  private handleDuplicate(
-    title: string,
-    ifExists: string,
-    input: Record<string, unknown>,
-  ): ToolExecutionResult | null {
-    const existing = findActiveWorkItemsByTitle(title);
-    if (existing.length === 0) return null;
-
-    const match = existing[0];
-    log.info({ title, existingId: match.id, ifExists }, 'task_list_add: duplicate detected');
-
-    if (ifExists === 'reuse_existing') {
-      log.info({ title, existingId: match.id }, 'task_list_add: reused existing item');
-      return {
-        content: `Task "${match.title}" already exists in the queue (ID: ${match.id}, status: ${match.status}). Use task_list_update to modify it.`,
-        isError: false,
-      };
+  if (ifExists === 'update_existing') {
+    const updates: Partial<{ title: string; notes: string; priorityTier: number; sortIndex: number }> = {};
+    if (input.priority_tier !== undefined) updates.priorityTier = input.priority_tier as number;
+    if (input.notes !== undefined) updates.notes = input.notes as string;
+    if (input.sort_index !== undefined) updates.sortIndex = input.sort_index as number;
+    if (Object.keys(updates).length > 0) {
+      updateWorkItem(match.id, updates);
     }
-
-    if (ifExists === 'update_existing') {
-      const updates: Partial<{ title: string; notes: string; priorityTier: number; sortIndex: number }> = {};
-      if (input.priority_tier !== undefined) updates.priorityTier = input.priority_tier as number;
-      if (input.notes !== undefined) updates.notes = input.notes as string;
-      if (input.sort_index !== undefined) updates.sortIndex = input.sort_index as number;
-      if (Object.keys(updates).length > 0) {
-        updateWorkItem(match.id, updates);
-      }
-      log.info({ title, existingId: match.id, updates }, 'task_list_add: updated existing item');
-      return {
-        content: `Reused existing task "${match.title}" (ID: ${match.id}) instead of creating a duplicate.${
-          Object.keys(updates).length > 0 ? ` Updated: ${Object.keys(updates).join(', ')}.` : ''
-        }`,
-        isError: false,
-      };
-    }
-
-    return null;
+    log.info({ title, existingId: match.id, updates }, 'task_list_add: updated existing item');
+    return {
+      content: `Reused existing task "${match.title}" (ID: ${match.id}) instead of creating a duplicate.${
+        Object.keys(updates).length > 0 ? ` Updated: ${Object.keys(updates).join(', ')}.` : ''
+      }`,
+      isError: false,
+    };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    try {
-      const taskId = input.task_id as string | undefined;
-      const taskName = input.task_name as string | undefined;
-      const titleOverride = input.title as string | undefined;
-      const notes = input.notes as string | undefined;
-      const priorityTier = input.priority_tier as number | undefined;
-      const sortIndex = input.sort_index as number | undefined;
-
-      const ifExists = (input.if_exists as string) || 'reuse_existing';
-
-      // Ad-hoc mode: title provided without task_id or task_name
-      if (!taskId && !taskName) {
-        if (!titleOverride) {
-          return {
-            content: 'Error: You must provide either task_id, task_name, or title to create a work item.',
-            isError: true,
-          };
-        }
-
-        // Duplicate-prevention guard
-        if (ifExists !== 'create_duplicate') {
-          const duplicateResult = this.handleDuplicate(titleOverride, ifExists, input);
-          if (duplicateResult) return duplicateResult;
-        } else {
-          log.info({ title: titleOverride }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
-        }
-
-        log.debug({ title: titleOverride }, 'task_list_add: creating new item');
-
-        // Auto-create a lightweight task template for the ad-hoc item
-        const adHocTask = createTask({
-          title: titleOverride,
-          template: titleOverride,
-        });
-
-        const workItem = createWorkItem({
-          taskId: adHocTask.id,
-          title: titleOverride,
-          notes,
-          priorityTier: priorityTier ?? 1,
-          sortIndex,
-        });
-
-        log.info({ selectorType: 'title', workItemId: workItem.id, title: workItem.title }, 'ad-hoc work item created');
-
-        const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
-        const lines = [
-          `Enqueued work item:`,
-          `  Title: ${workItem.title}`,
-          `  ID: ${workItem.id}`,
-          `  Priority: ${priority}`,
-          `  Status: ${workItem.status}`,
-        ];
-        if (workItem.notes) {
-          lines.push(`  Notes: ${workItem.notes}`);
-        }
-        if (workItem.sortIndex !== null) {
-          lines.push(`  Sort index: ${workItem.sortIndex}`);
-        }
-
-        return { content: lines.join('\n'), isError: false };
-      }
-
-      let resolvedTask;
-
-      if (taskId) {
-        resolvedTask = getTask(taskId);
-        if (!resolvedTask) {
-          const entity = identifyEntityById(taskId);
-          if (entity.type === 'work_item') {
-            return {
-              content: `Error: ${buildWorkItemMismatchError(taskId, entity.title!, 'task_list_update to modify the existing work item, or task_list_add with just a title for a new ad-hoc item')}`,
-              isError: true,
-            };
-          }
-          return { content: `Error: No task definition found with ID "${taskId}". Use task_list to see available task templates, or provide just a title to create an ad-hoc work item.`, isError: true };
-        }
-      } else {
-        // Search by name (case-insensitive substring match)
-        const needle = taskName!.toLowerCase();
-        const allTasks = listTasks();
-        const matches = allTasks.filter((t) => t.title.toLowerCase().includes(needle));
-
-        if (matches.length === 0) {
-          return {
-            content: `Error: No task definition found matching "${taskName}". Use task_list to see available tasks.`,
-            isError: true,
-          };
-        }
-
-        if (matches.length > 1) {
-          const lines = [
-            `Multiple task definitions match "${taskName}". Please specify by ID:`,
-            '',
-          ];
-          for (const m of matches) {
-            lines.push(`- ${m.title}  (ID: ${m.id})`);
-          }
-          return { content: lines.join('\n'), isError: true };
-        }
+  return null;
+}
 
-        resolvedTask = matches[0];
+export async function executeTaskListAdd(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  try {
+    const taskId = input.task_id as string | undefined;
+    const taskName = input.task_name as string | undefined;
+    const titleOverride = input.title as string | undefined;
+    const executionPrompt = input.execution_prompt as string | undefined;
+    const notes = input.notes as string | undefined;
+    const priorityTier = input.priority_tier as number | undefined;
+    const sortIndex = input.sort_index as number | undefined;
+    const rawRequiredTools = input.required_tools as string[] | undefined;
+
+    const ifExists = (input.if_exists as string) || 'reuse_existing';
+
+    // Sanitize explicit required_tools if provided (including empty array)
+    const hasExplicitTools = rawRequiredTools !== undefined;
+    const sanitizedTools = hasExplicitTools ? sanitizeToolList(rawRequiredTools) : undefined;
+
+    // Ad-hoc mode: title provided without task_id or task_name
+    if (!taskId && !taskName) {
+      if (!titleOverride) {
+        return {
+          content: 'Error: You must provide either task_id, task_name, or title to create a work item.',
+          isError: true,
+        };
       }
 
-      const finalTitle = titleOverride ?? resolvedTask.title;
-
       // Duplicate-prevention guard
       if (ifExists !== 'create_duplicate') {
-        const duplicateResult = this.handleDuplicate(finalTitle, ifExists, input);
+        const duplicateResult = handleDuplicate(titleOverride, ifExists, input);
         if (duplicateResult) return duplicateResult;
       } else {
-        log.info({ title: finalTitle }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
+        log.info({ title: titleOverride }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
       }
 
-      log.debug({ title: finalTitle }, 'task_list_add: creating new item');
+      log.debug({ title: titleOverride }, 'task_list_add: creating new item');
+
+      // Auto-create a lightweight task template for the ad-hoc item.
+      // Use execution_prompt as the template (the actual instruction sent to the
+      // model at run time), falling back to notes then title. This preserves
+      // detailed instructions (e.g. full file paths) that may be shortened in
+      // the display title.
+      const adHocTemplate = executionPrompt ?? notes ?? titleOverride;
+      const adHocTask = createTask({
+        title: titleOverride,
+        template: adHocTemplate,
+      });
 
-      const selectorType = taskId ? 'task_id' : 'task_name';
-      const workItem = createWorkItem({
-        taskId: resolvedTask.id,
-        title: finalTitle,
+      // For ad-hoc items: explicit tools → persist; omitted → null
+      const adHocRequiredTools = hasExplicitTools ? JSON.stringify(sanitizedTools) : undefined;
+
+      const workItem = createWorkItemWithPermissions({
+        taskId: adHocTask.id,
+        title: titleOverride,
         notes,
         priorityTier: priorityTier ?? 1,
         sortIndex,
+        requiredTools: adHocRequiredTools,
       });
 
-      log.info({ selectorType, taskId: resolvedTask.id, workItemId: workItem.id, title: workItem.title }, 'work item created from task definition');
+      log.info({ selectorType: 'title', workItemId: workItem.id, title: workItem.title }, 'ad-hoc work item created');
 
       const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
       const lines = [
         `Enqueued work item:`,
         `  Title: ${workItem.title}`,
         `  ID: ${workItem.id}`,
-        `  Task definition: ${resolvedTask.title} (${resolvedTask.id})`,
         `  Priority: ${priority}`,
         `  Status: ${workItem.status}`,
       ];
@@ -255,12 +131,104 @@ class TaskListAddTool implements Tool {
       }
 
       return { content: lines.join('\n'), isError: false };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      log.error({ error: msg }, 'enqueue failed');
-      return { content: `Error: ${msg}`, isError: true };
     }
+
+    let resolvedTask;
+
+    if (taskId) {
+      resolvedTask = getTask(taskId);
+      if (!resolvedTask) {
+        const entity = identifyEntityById(taskId);
+        if (entity.type === 'work_item') {
+          return {
+            content: `Error: ${buildWorkItemMismatchError(taskId, entity.title!, 'task_list_update to modify the existing work item, or task_list_add with just a title for a new ad-hoc item')}`,
+            isError: true,
+          };
+        }
+        return { content: `Error: No task definition found with ID "${taskId}". Use task_list to see available task templates, or provide just a title to create an ad-hoc work item.`, isError: true };
+      }
+    } else {
+      // Search by name (case-insensitive substring match)
+      const needle = taskName!.toLowerCase();
+      const allTasks = listTasks();
+      const matches = allTasks.filter((t) => t.title.toLowerCase().includes(needle));
+
+      if (matches.length === 0) {
+        return {
+          content: `Error: No task definition found matching "${taskName}". Use task_list to see available tasks.`,
+          isError: true,
+        };
+      }
+
+      if (matches.length > 1) {
+        const lines = [
+          `Multiple task definitions match "${taskName}". Please specify by ID:`,
+          '',
+        ];
+        for (const m of matches) {
+          lines.push(`- ${m.title}  (ID: ${m.id})`);
+        }
+        return { content: lines.join('\n'), isError: true };
+      }
+
+      resolvedTask = matches[0];
+    }
+
+    const finalTitle = titleOverride ?? resolvedTask.title;
+
+    // Duplicate-prevention guard
+    if (ifExists !== 'create_duplicate') {
+      const duplicateResult = handleDuplicate(finalTitle, ifExists, input);
+      if (duplicateResult) return duplicateResult;
+    } else {
+      log.info({ title: finalTitle }, 'task_list_add: creating duplicate (if_exists=create_duplicate)');
+    }
+
+    log.debug({ title: finalTitle }, 'task_list_add: creating new item');
+
+    const selectorType = taskId ? 'task_id' : 'task_name';
+
+    // Snapshot precedence: explicit required_tools > template tools > null
+    let resolvedRequiredTools: string | undefined;
+    if (hasExplicitTools) {
+      resolvedRequiredTools = JSON.stringify(sanitizedTools);
+    } else if (resolvedTask.requiredTools) {
+      // Snapshot template tools at add time
+      const templateTools = sanitizeToolList(JSON.parse(resolvedTask.requiredTools));
+      resolvedRequiredTools = JSON.stringify(templateTools);
+    }
+
+    const workItem = createWorkItemWithPermissions({
+      taskId: resolvedTask.id,
+      title: finalTitle,
+      notes,
+      priorityTier: priorityTier ?? 1,
+      sortIndex,
+      requiredTools: resolvedRequiredTools,
+    });
+
+    log.info({ selectorType, taskId: resolvedTask.id, workItemId: workItem.id, title: workItem.title }, 'work item created from task definition');
+
+    const priority = PRIORITY_LABELS[workItem.priorityTier] ?? `tier ${workItem.priorityTier}`;
+    const lines = [
+      `Enqueued work item:`,
+      `  Title: ${workItem.title}`,
+      `  ID: ${workItem.id}`,
+      `  Task definition: ${resolvedTask.title} (${resolvedTask.id})`,
+      `  Priority: ${priority}`,
+      `  Status: ${workItem.status}`,
+    ];
+    if (workItem.notes) {
+      lines.push(`  Notes: ${workItem.notes}`);
+    }
+    if (workItem.sortIndex !== null) {
+      lines.push(`  Sort index: ${workItem.sortIndex}`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ error: msg }, 'enqueue failed');
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-export const taskListAddTool = new TaskListAddTool();

package/src/tools/tasks/work-item-list.ts

@@ -1,71 +1,41 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { listWorkItems, type WorkItemStatus } from '../../work-items/work-item-store.js';
 
-const definition: ToolDefinition = {
-  name: 'task_list_show',
-  description: 'List the user\'s Task Queue (work items) with their status, priority, and last run info. Use this when the user says "show my tasks", "what\'s in my queue", "what\'s on my task list", or similar.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      status: {
-        oneOf: [
-          { type: 'string' },
-          { type: 'array', items: { type: 'string' } },
-        ],
-        description:
-          'Optional status filter. A single status string (e.g. "queued") or an array of statuses to include.',
-      },
-    },
-  },
-};
-
-class TaskListShowTool implements Tool {
-  name = 'task_list_show';
-  description = definition.description;
-  category = 'tasks';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
-  }
-
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    try {
-      const statusFilter = input.status as string | string[] | undefined;
-
-      let items;
-      if (typeof statusFilter === 'string') {
-        items = listWorkItems({ status: statusFilter as WorkItemStatus });
-      } else if (Array.isArray(statusFilter)) {
-        // listWorkItems only supports a single status filter, so we fetch all
-        // and filter client-side when an array is provided
-        const allItems = listWorkItems();
-        const allowed = new Set(statusFilter);
-        items = allItems.filter((item) => allowed.has(item.status));
-      } else {
-        items = listWorkItems();
-      }
+export async function executeTaskListShow(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  try {
+    const statusFilter = input.status as string | string[] | undefined;
+
+    let items;
+    if (typeof statusFilter === 'string') {
+      items = listWorkItems({ status: statusFilter as WorkItemStatus });
+    } else if (Array.isArray(statusFilter)) {
+      // listWorkItems only supports a single status filter, so we fetch all
+      // and filter client-side when an array is provided
+      const allItems = listWorkItems();
+      const allowed = new Set(statusFilter);
+      items = allItems.filter((item) => allowed.has(item.status));
+    } else {
+      items = listWorkItems();
+    }
 
-      const count = items.length;
-      const filtered = statusFilter !== undefined;
+    const count = items.length;
+    const filtered = statusFilter !== undefined;
 
-      if (count === 0) {
-        const suffix = filtered ? 'no items matching filter.' : 'no tasks queued.';
-        return { content: `Opened Tasks window \u2014 ${suffix}`, isError: false };
-      }
+    if (count === 0) {
+      const suffix = filtered ? 'no items matching filter.' : 'no tasks queued.';
+      return { content: `Opened Tasks window \u2014 ${suffix}`, isError: false };
+    }
 
-      const label = filtered
-        ? `${count} ${Array.isArray(statusFilter) ? 'matching' : statusFilter} item${count === 1 ? '' : 's'}`
-        : `${count} item${count === 1 ? '' : 's'}`;
+    const label = filtered
+      ? `${count} ${Array.isArray(statusFilter) ? 'matching' : statusFilter} item${count === 1 ? '' : 's'}`
+      : `${count} item${count === 1 ? '' : 's'}`;
 
-      return { content: `Opened Tasks window (${label}).`, isError: false };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
-    }
+    return { content: `Opened Tasks window (${label}).`, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-export const taskListShowTool = new TaskListShowTool();