vellum 0.2.1 → 0.2.2

package/src/tools/document/document-tool.ts

@@ -1,165 +1,92 @@
-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 { randomUUID } from 'node:crypto';
 
-// ── document_create ──────────────────────────────────────────────────
-
-export class DocumentCreateTool implements Tool {
-  name = 'document_create';
-  description =
-    'Create a new long-form document with a rich text editor. Use this when the user asks to write a blog post, article, or any long-form content. The editor opens in workspace mode with chat docked to the side.';
-  category = 'document';
-  defaultRiskLevel = RiskLevel.Low;
-  executionMode = 'local' as const;
-
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          title: {
-            type: 'string',
-            description: 'Initial title for the document (optional, can be updated later)',
-          },
-          initial_content: {
-            type: 'string',
-            description: 'Initial Markdown content to populate the editor (optional)',
-          },
-        },
-      },
-    };
-  }
-
-  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
-    const title = (input.title as string | undefined) || 'Untitled Document';
-    const initialContent = (input.initial_content as string | undefined) || '';
-    const surfaceId = `doc-${randomUUID()}`;
-
-    // Send document_editor_show IPC message to open the built-in RTE
-    if (context.sendToClient) {
-      context.sendToClient({
-        type: 'document_editor_show',
-        sessionId: context.sessionId,
-        surfaceId,
-        title,
-        initialContent,
-      });
-
-      context.sendToClient({
-        type: 'ui_surface_show',
-        sessionId: context.sessionId,
-        surfaceId: `preview-${surfaceId}`,
-        surfaceType: 'document_preview',
-        display: 'inline',
+// ── Exported execute functions ──────────────────────────────────────
+
+export function executeDocumentCreate(input: Record<string, unknown>, context: ToolContext): ToolExecutionResult {
+  const title = (input.title as string | undefined) || 'Untitled Document';
+  const initialContent = (input.initial_content as string | undefined) || '';
+  const surfaceId = `doc-${randomUUID()}`;
+
+  // Send document_editor_show IPC message to open the built-in RTE
+  if (context.sendToClient) {
+    context.sendToClient({
+      type: 'document_editor_show',
+      sessionId: context.sessionId,
+      surfaceId,
+      title,
+      initialContent,
+    });
+
+    context.sendToClient({
+      type: 'ui_surface_show',
+      sessionId: context.sessionId,
+      surfaceId: `preview-${surfaceId}`,
+      surfaceType: 'document_preview',
+      display: 'inline',
+      title,
+      data: {
         title,
-        data: {
-          title,
-          surfaceId,
-          subtitle: 'Document',
-        },
-      });
-
-      return {
-        content: JSON.stringify({
-          surface_id: surfaceId,
-          title,
-          opened: true,
-          message: 'Document editor opened in Directory panel',
-        }),
-        isError: false,
-      };
-    }
+        surfaceId,
+        subtitle: 'Document',
+      },
+    });
 
-    // Fallback if no IPC client is connected
     return {
       content: JSON.stringify({
         surface_id: surfaceId,
         title,
-        opened: false,
-        error: 'No IPC client connected to open document editor',
+        opened: true,
+        message: 'Document editor opened in Directory panel',
       }),
       isError: false,
     };
   }
-}
-
-// ── document_update ──────────────────────────────────────────────────
-
-export class DocumentUpdateTool implements Tool {
-  name = 'document_update';
-  description =
-    'Update content in an open document editor. Use this to stream generated content or apply edits.';
-  category = 'document';
-  defaultRiskLevel = RiskLevel.Low;
-  executionMode = 'local' as const;
-
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          surface_id: {
-            type: 'string',
-            description: 'The ID of the document surface to update',
-          },
-          content: {
-            type: 'string',
-            description: 'Markdown content to set or append',
-          },
-          mode: {
-            type: 'string',
-            enum: ['replace', 'append'],
-            description: 'Whether to replace all content or append to the end. Defaults to append.',
-          },
-        },
-        required: ['surface_id', 'content'],
-      },
-    };
-  }
 
-  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
-    const surfaceId = input.surface_id as string;
-    const content = input.content as string;
-    const mode = (input.mode as string | undefined) || 'append';
-
-    // Send document_editor_update IPC message to update the built-in RTE
-    if (context.sendToClient) {
-      context.sendToClient({
-        type: 'document_editor_update',
-        sessionId: context.sessionId,
-        surfaceId,
-        markdown: content,
-        mode,
-      });
+  // Fallback if no IPC client is connected
+  return {
+    content: JSON.stringify({
+      surface_id: surfaceId,
+      title,
+      opened: false,
+      error: 'No IPC client connected to open document editor',
+    }),
+    isError: false,
+  };
+}
 
-      return {
-        content: JSON.stringify({
-          success: true,
-          surface_id: surfaceId,
-          mode,
-          message: 'Document content updated',
-        }),
-        isError: false,
-      };
-    }
+export function executeDocumentUpdate(input: Record<string, unknown>, context: ToolContext): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  const content = input.content as string;
+  const mode = (input.mode as string | undefined) || 'append';
+
+  // Send document_editor_update IPC message to update the built-in RTE
+  if (context.sendToClient) {
+    context.sendToClient({
+      type: 'document_editor_update',
+      sessionId: context.sessionId,
+      surfaceId,
+      markdown: content,
+      mode,
+    });
 
-    // Fallback if no IPC client is connected
     return {
       content: JSON.stringify({
-        success: false,
-        error: 'No IPC client connected to update document',
+        success: true,
+        surface_id: surfaceId,
+        mode,
+        message: 'Document content updated',
       }),
-      isError: true,
+      isError: false,
     };
   }
-}
 
-// ── Exported tool instances ──────────────────────────────────────────
-
-export const documentCreateTool = new DocumentCreateTool();
-export const documentUpdateTool = new DocumentUpdateTool();
+  // Fallback if no IPC client is connected
+  return {
+    content: JSON.stringify({
+      success: false,
+      error: 'No IPC client connected to update document',
+    }),
+    isError: true,
+  };
+}

package/src/tools/executor.ts

@@ -17,6 +17,7 @@ import { getConfig } from '../config/loader.js';
 import { scanText, redactSecrets } from '../security/secret-scanner.js';
 import { redactSensitiveFields } from '../security/redaction.js';
 import { getHookManager } from '../hooks/manager.js';
+import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
 
 const log = getLogger('tool-executor');
 
@@ -67,10 +68,39 @@ export class ToolExecutor {
         durationMs,
         errorMessage: msg,
         isExpected: true,
+        errorCategory: 'tool_failure',
       });
       return { content: msg, isError: true };
     }
 
+    // Belt-and-suspenders guard for task runs: only preflight-approved tools
+    // may execute. This catches cases where ephemeral rules might not cover
+    // a tool, ensuring unapproved calls fail deterministically instead of
+    // falling through to the interactive prompter.
+    if (context.taskRunId) {
+      const taskRules = getTaskRunRules(context.taskRunId);
+      const approvedToolNames = new Set(taskRules.map((r) => r.tool));
+      if (approvedToolNames.size > 0 && !approvedToolNames.has(name)) {
+        const msg = `Tool '${name}' was not approved in the task's preflight. Add it to required tools and re-approve.`;
+        const durationMs = Date.now() - startTime;
+        emitLifecycleEvent(context, {
+          type: 'permission_denied',
+          toolName: name,
+          executionTarget,
+          input,
+          workingDir: context.workingDir,
+          sessionId: context.sessionId,
+          conversationId: context.conversationId,
+          requestId: context.requestId,
+          riskLevel,
+          decision: 'deny',
+          reason: msg,
+          durationMs,
+        });
+        return { content: msg, isError: true };
+      }
+    }
+
     const tool = getTool(name);
     if (!tool) {
       const available = getAllTools().filter((t) => t.executionMode !== 'proxy' || context.proxyToolResolver).map((t) => t.name).sort().join(', ');
@@ -90,6 +120,7 @@ export class ToolExecutor {
         durationMs,
         errorMessage: msg,
         isExpected: true,
+        errorCategory: 'tool_failure',
       });
       return { content: msg, isError: true };
     }
@@ -100,8 +131,9 @@ export class ToolExecutor {
       riskLevel = risk;
 
       // Build principal context from tool metadata so policy rules can
-      // distinguish skill-provided tools from core built-ins.
-      const policyContext = buildPolicyContext(tool);
+      // distinguish skill-provided tools from core built-ins. Also includes
+      // ephemeral rules when executing within a task run.
+      const policyContext = buildPolicyContext(tool, context);
       const result = await check(name, input, context.workingDir, policyContext);
 
       // Private threads force prompting for side-effect tools even when a
@@ -137,6 +169,32 @@ export class ToolExecutor {
       }
 
       if (result.decision === 'prompt') {
+        // Non-interactive sessions have no client to respond to prompts —
+        // deny immediately instead of blocking for the full permission timeout.
+        if (context.isInteractive === false) {
+          decision = 'denied';
+          const durationMs = Date.now() - startTime;
+          log.info({ toolName: name, riskLevel }, 'Auto-denying prompt for non-interactive session');
+          emitLifecycleEvent(context, {
+            type: 'permission_denied',
+            toolName: name,
+            executionTarget,
+            input,
+            workingDir: context.workingDir,
+            sessionId: context.sessionId,
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            riskLevel,
+            decision: 'deny',
+            reason: 'Non-interactive session: no client to approve prompt',
+            durationMs,
+          });
+          return {
+            content: `Permission denied: tool "${name}" requires user approval but no interactive client is connected. The tool was not executed. To allow this tool in non-interactive sessions, add a trust rule via permission settings.`,
+            isError: true,
+          };
+        }
+
         // Need user approval
         const allowlistOptions = generateAllowlistOptions(name, input);
         const scopeOptions = generateScopeOptions(context.workingDir, name);
@@ -325,6 +383,7 @@ export class ToolExecutor {
           durationMs,
           errorMessage: msg,
           isExpected: true,
+          errorCategory: 'tool_failure',
         });
         return { content: msg, isError: true };
       }
@@ -358,6 +417,7 @@ export class ToolExecutor {
             durationMs,
             errorMessage: msg,
             isExpected: true,
+            errorCategory: 'tool_failure',
           });
           return { content: msg, isError: true };
         }
@@ -464,6 +524,39 @@ export class ToolExecutor {
           } else if (sdConfig.action === 'prompt') {
             // Ask the user whether to allow tool output containing secrets
             const types = [...new Set(allMatches.map((m) => m.type))].join(', ');
+
+            // Non-interactive sessions: auto-block secret output instead of waiting for prompt
+            if (context.isInteractive === false) {
+              const blockedContent = `Tool output blocked: detected ${allMatches.length} potential secret(s) (${types}). No interactive client available to approve.`;
+              const durationMs = Date.now() - startTime;
+              log.info({ toolName: name }, 'Auto-blocking secret output for non-interactive session');
+              emitLifecycleEvent(context, {
+                type: 'permission_denied',
+                toolName: name,
+                executionTarget,
+                input,
+                workingDir: context.workingDir,
+                sessionId: context.sessionId,
+                conversationId: context.conversationId,
+                requestId: context.requestId,
+                riskLevel: RiskLevel.High,
+                decision: 'deny',
+                reason: 'Non-interactive session: auto-blocked secret output',
+                durationMs,
+              });
+
+              void getHookManager().trigger('post-tool-execute', {
+                toolName: name,
+                input: sanitizeToolInput(name, input),
+                riskLevel,
+                isError: true,
+                durationMs,
+                sessionId: context.sessionId,
+              });
+
+              return { content: blockedContent, isError: true };
+            }
+
             const promptInput = {
               _secretDetection: true,
               summary: `Tool output contains ${allMatches.length} potential secret(s): ${types}`,
@@ -565,6 +658,14 @@ export class ToolExecutor {
       const msg = err instanceof Error ? err.message : String(err);
       const isExpected = err instanceof PermissionDeniedError || err instanceof ToolError || err instanceof TokenExpiredError;
 
+      const errorCategory = err instanceof PermissionDeniedError
+        ? 'permission_denied' as const
+        : err instanceof TokenExpiredError
+          ? 'auth' as const
+          : err instanceof ToolError
+            ? 'tool_failure' as const
+            : 'unexpected' as const;
+
       emitLifecycleEvent(context, {
         type: 'error',
         toolName: name,
@@ -579,6 +680,7 @@ export class ToolExecutor {
         durationMs,
         errorMessage: msg,
         isExpected,
+        errorCategory,
         errorName: err instanceof Error ? err.name : undefined,
         errorStack: err instanceof Error ? err.stack : undefined,
       });
@@ -622,6 +724,8 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
   'browser_fill_credential',
   'document_create',
   'document_update',
+  'reminder_create',
+  'reminder_cancel',
   'schedule_create',
   'schedule_update',
   'schedule_delete',
@@ -644,10 +748,6 @@ export function isSideEffectTool(toolName: string, input?: Record<string, unknow
     const action = input?.action;
     return action === 'create' || action === 'update';
   }
-  if (toolName === 'reminder') {
-    const action = input?.action;
-    return action === 'create' || action === 'cancel';
-  }
   if (toolName === 'credential_store') {
     const action = input?.action;
     return action === 'store' || action === 'delete' || action === 'prompt' || action === 'oauth2_connect';
@@ -705,11 +805,16 @@ async function executeWithTimeout(
 }
 
 /**
- * Build a PolicyContext from tool metadata. Skill-origin tools carry a
- * principal identifying the owning skill; core tools yield an undefined
- * context so the checker applies default (user) policy.
+ * Build a PolicyContext from tool metadata and execution context. Skill-origin
+ * tools carry a principal identifying the owning skill. When executing within
+ * a task run, ephemeral permission rules are included so pre-approved tools
+ * are auto-allowed without prompting.
  */
-function buildPolicyContext(tool: Tool): PolicyContext | undefined {
+function buildPolicyContext(tool: Tool, context?: ToolContext): PolicyContext | undefined {
+  const ephemeralRules = context?.taskRunId
+    ? getTaskRunRules(context.taskRunId)
+    : undefined;
+
   if (tool.origin === 'skill') {
     return {
       principal: {
@@ -718,8 +823,22 @@ function buildPolicyContext(tool: Tool): PolicyContext | undefined {
         version: tool.ownerSkillVersionHash,
       },
       executionTarget: tool.executionTarget,
+      ephemeralRules: ephemeralRules?.length ? ephemeralRules : undefined,
     };
   }
+
+  // For non-skill tools in a task run, create a context with task principal
+  // and ephemeral rules so pre-approved tools are honored.
+  if (context?.taskRunId && ephemeralRules?.length) {
+    return {
+      principal: {
+        kind: 'task',
+        id: context.taskRunId,
+      },
+      ephemeralRules,
+    };
+  }
+
   return undefined;
 }
 

package/src/tools/followups/followup_create.ts

@@ -1,6 +1,4 @@
-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 { createFollowUp } from '../../followups/followup-store.js';
 import { getContact } from '../../contacts/contact-store.js';
 import type { FollowUp } from '../../followups/types.js';
@@ -17,102 +15,62 @@ function formatFollowUp(f: FollowUp): string {
   if (f.expectedResponseBy) {
     lines.push(`  Expected response by: ${new Date(f.expectedResponseBy).toISOString()}`);
   }
-  if (f.reminderCronId) lines.push(`  Reminder cron: ${f.reminderCronId}`);
+  if (f.reminderScheduleId) lines.push(`  Reminder schedule: ${f.reminderScheduleId}`);
   return lines.join('\n');
 }
 
-const definition: ToolDefinition = {
-  name: 'followup_create',
-  description: 'Create a follow-up tracker for a sent message. Tracks conversations awaiting a response across channels (email, Slack, WhatsApp, etc.).',
-  input_schema: {
-    type: 'object',
-    properties: {
-      channel: {
-        type: 'string',
-        description: 'Communication channel (e.g. email, slack, whatsapp)',
-      },
-      thread_id: {
-        type: 'string',
-        description: 'External thread or conversation identifier on that channel',
-      },
-      contact_id: {
-        type: 'string',
-        description: 'Optional contact ID from the contact graph. Used for grace period context.',
-      },
-      expected_response_hours: {
-        type: 'number',
-        description: 'Hours to wait for a response before marking as overdue. If omitted, no deadline is set.',
-      },
-      reminder_cron_id: {
-        type: 'string',
-        description: 'Optional cron job ID to fire a reminder when overdue',
-      },
-    },
-    required: ['channel', 'thread_id'],
-  },
-};
-
-class FollowUpCreateTool implements Tool {
-  name = 'followup_create';
-  description = definition.description;
-  category = 'followups';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+export async function executeFollowupCreate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const channel = input.channel as string | undefined;
+  if (!channel || typeof channel !== 'string' || channel.trim().length === 0) {
+    return { content: 'Error: channel is required and must be a non-empty string', isError: true };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const channel = input.channel as string | undefined;
-    if (!channel || typeof channel !== 'string' || channel.trim().length === 0) {
-      return { content: 'Error: channel is required and must be a non-empty string', isError: true };
-    }
-
-    const threadId = input.thread_id as string | undefined;
-    if (!threadId || typeof threadId !== 'string' || threadId.trim().length === 0) {
-      return { content: 'Error: thread_id is required and must be a non-empty string', isError: true };
-    }
+  const threadId = input.thread_id as string | undefined;
+  if (!threadId || typeof threadId !== 'string' || threadId.trim().length === 0) {
+    return { content: 'Error: thread_id is required and must be a non-empty string', isError: true };
+  }
 
-    const contactId = input.contact_id as string | undefined;
-    const expectedResponseHours = input.expected_response_hours as number | undefined;
-    const reminderCronId = input.reminder_cron_id as string | undefined;
+  const contactId = input.contact_id as string | undefined;
+  const expectedResponseHours = input.expected_response_hours as number | undefined;
+  // Canonical: reminder_schedule_id; deprecated alias: reminder_cron_id
+  const reminderScheduleId = (input.reminder_schedule_id ?? input.reminder_cron_id) as string | undefined;
 
-    // Validate contact exists if provided
-    if (contactId) {
-      const contact = getContact(contactId);
-      if (!contact) {
-        return { content: `Error: Contact "${contactId}" not found`, isError: true };
-      }
+  // Validate contact exists if provided
+  if (contactId) {
+    const contact = getContact(contactId);
+    if (!contact) {
+      return { content: `Error: Contact "${contactId}" not found`, isError: true };
     }
+  }
 
-    if (expectedResponseHours !== undefined && (typeof expectedResponseHours !== 'number' || expectedResponseHours <= 0)) {
-      return { content: 'Error: expected_response_hours must be a positive number', isError: true };
-    }
+  if (expectedResponseHours !== undefined && (typeof expectedResponseHours !== 'number' || expectedResponseHours <= 0)) {
+    return { content: 'Error: expected_response_hours must be a positive number', isError: true };
+  }
 
-    try {
-      const now = Date.now();
-      const expectedResponseBy = expectedResponseHours
-        ? now + expectedResponseHours * 60 * 60 * 1000
-        : null;
+  try {
+    const now = Date.now();
+    const expectedResponseBy = expectedResponseHours
+      ? now + expectedResponseHours * 60 * 60 * 1000
+      : null;
 
-      const followUp = createFollowUp({
-        channel: channel.trim(),
-        threadId: threadId.trim(),
-        contactId: contactId ?? null,
-        sentAt: now,
-        expectedResponseBy,
-        reminderCronId: reminderCronId ?? null,
-      });
+    const followUp = createFollowUp({
+      channel: channel.trim(),
+      threadId: threadId.trim(),
+      contactId: contactId ?? null,
+      sentAt: now,
+      expectedResponseBy,
+      reminderScheduleId: reminderScheduleId ?? null,
+    });
 
-      return {
-        content: `Created follow-up:\n${formatFollowUp(followUp)}`,
-        isError: false,
-      };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
-    }
+    return {
+      content: `Created follow-up:\n${formatFollowUp(followUp)}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-export const followupCreateTool = new FollowUpCreateTool();