@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/agent-tools/tools/enterprise-workflow.ts

@@ -0,0 +1,308 @@
+/**
+ * AgenticMail Agent Tools — Enterprise Workflow
+ *
+ * File-based approval workflow system. Stores workflow requests
+ * as JSON in {workspaceDir}/.agenticmail/workflows.json with
+ * atomic writes and UUID-based identification.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import type { AnyAgentTool, ToolCreationOptions } from '../types.js';
+import { readStringParam, readNumberParam, readStringArrayParam, textResult, jsonResult, errorResult } from '../common.js';
+
+type WorkflowStatus = 'pending' | 'approved' | 'rejected' | 'cancelled';
+
+type WorkflowRequest = {
+  id: string;
+  type: string;
+  title: string;
+  description: string;
+  requestedBy: string;
+  status: WorkflowStatus;
+  createdAt: string;
+  updatedAt: string;
+  approvers: string[];
+  metadata: Record<string, unknown>;
+  cancelReason?: string;
+  lastRemindedAt?: string;
+};
+
+type WorkflowStore = {
+  requests: WorkflowRequest[];
+};
+
+async function loadWorkflowStore(storePath: string): Promise<WorkflowStore> {
+  try {
+    var content = await fs.readFile(storePath, 'utf-8');
+    return JSON.parse(content) as WorkflowStore;
+  } catch {
+    return { requests: [] };
+  }
+}
+
+async function saveWorkflowStore(storePath: string, store: WorkflowStore): Promise<void> {
+  var dir = path.dirname(storePath);
+  await fs.mkdir(dir, { recursive: true });
+  var data = JSON.stringify(store, null, 2);
+  var tmpPath = storePath + '.tmp.' + crypto.randomBytes(4).toString('hex');
+  try {
+    await fs.writeFile(tmpPath, data, 'utf-8');
+    await fs.rename(tmpPath, storePath);
+  } catch (err) {
+    try { await fs.unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+export function createEnterpriseWorkflowTools(options?: ToolCreationOptions): AnyAgentTool[] {
+  var storePath = path.join(
+    options?.workspaceDir || process.cwd(),
+    '.agenticmail',
+    'workflows.json',
+  );
+
+  return [
+    {
+      name: 'ent_wf_request_approval',
+      label: 'Request Approval',
+      description: 'Create a new approval request in the enterprise workflow system. Supports expense, access, change, deploy, and custom request types.',
+      category: 'utility',
+      risk: 'medium',
+      parameters: {
+        type: 'object',
+        properties: {
+          type: { type: 'string', description: 'Request type.', enum: ['expense', 'access', 'change', 'deploy', 'custom'] },
+          title: { type: 'string', description: 'Short title for the approval request.' },
+          description: { type: 'string', description: 'Detailed description of what needs approval.' },
+          requested_by: { type: 'string', description: 'Name or email of the person requesting approval.' },
+          approvers: { type: 'string', description: 'Comma-separated list of approver names or emails.' },
+          metadata: { type: 'string', description: 'Optional JSON string with additional metadata.' },
+        },
+        required: ['type', 'title', 'description', 'requested_by', 'approvers'],
+      },
+      execute: async function(_toolCallId, args) {
+        var params = args as Record<string, unknown>;
+        try {
+          var type = readStringParam(params, 'type', { required: true });
+          var title = readStringParam(params, 'title', { required: true });
+          var description = readStringParam(params, 'description', { required: true });
+          var requestedBy = readStringParam(params, 'requested_by', { required: true });
+          var approvers = readStringArrayParam(params, 'approvers', { required: true });
+          var metadataRaw = readStringParam(params, 'metadata');
+
+          var validTypes = ['expense', 'access', 'change', 'deploy', 'custom'];
+          if (validTypes.indexOf(type) === -1) {
+            return errorResult('Invalid type "' + type + '". Must be one of: ' + validTypes.join(', '));
+          }
+
+          var metadata: Record<string, unknown> = {};
+          if (metadataRaw) {
+            try {
+              metadata = JSON.parse(metadataRaw);
+            } catch {
+              return errorResult('Invalid metadata JSON.');
+            }
+          }
+
+          var now = new Date().toISOString();
+          var request: WorkflowRequest = {
+            id: crypto.randomUUID(),
+            type: type,
+            title: title,
+            description: description,
+            requestedBy: requestedBy,
+            status: 'pending',
+            createdAt: now,
+            updatedAt: now,
+            approvers: approvers,
+            metadata: metadata,
+          };
+
+          var store = await loadWorkflowStore(storePath);
+          store.requests.push(request);
+          await saveWorkflowStore(storePath, store);
+
+          return jsonResult(request);
+        } catch (err: any) {
+          return errorResult(err.message || 'Failed to create approval request.');
+        }
+      },
+    },
+    {
+      name: 'ent_wf_check_status',
+      label: 'Check Workflow Status',
+      description: 'Check the current status of an approval workflow request by its ID.',
+      category: 'utility',
+      risk: 'low',
+      parameters: {
+        type: 'object',
+        properties: {
+          request_id: { type: 'string', description: 'The UUID of the workflow request to check.' },
+        },
+        required: ['request_id'],
+      },
+      execute: async function(_toolCallId, args) {
+        var params = args as Record<string, unknown>;
+        try {
+          var requestId = readStringParam(params, 'request_id', { required: true });
+          var store = await loadWorkflowStore(storePath);
+          var request = store.requests.find(function(r) { return r.id === requestId; });
+
+          if (!request) {
+            return errorResult('Workflow request not found: ' + requestId);
+          }
+
+          return jsonResult(request);
+        } catch (err: any) {
+          return errorResult(err.message || 'Failed to check workflow status.');
+        }
+      },
+    },
+    {
+      name: 'ent_wf_list_pending',
+      label: 'List Pending Approvals',
+      description: 'List all pending approval requests, optionally filtered by type or requester.',
+      category: 'utility',
+      risk: 'low',
+      parameters: {
+        type: 'object',
+        properties: {
+          type: { type: 'string', description: 'Optional filter by request type (expense, access, change, deploy, custom).' },
+          requested_by: { type: 'string', description: 'Optional filter by requester name or email.' },
+          limit: { type: 'number', description: 'Maximum number of results to return (default 20).', default: 20 },
+        },
+      },
+      execute: async function(_toolCallId, args) {
+        var params = args as Record<string, unknown>;
+        try {
+          var typeFilter = readStringParam(params, 'type');
+          var requestedByFilter = readStringParam(params, 'requested_by');
+          var limit = readNumberParam(params, 'limit', { integer: true }) ?? 20;
+
+          var store = await loadWorkflowStore(storePath);
+          var pending = store.requests.filter(function(r) {
+            if (r.status !== 'pending') return false;
+            if (typeFilter && r.type !== typeFilter) return false;
+            if (requestedByFilter && r.requestedBy !== requestedByFilter) return false;
+            return true;
+          });
+
+          // Sort by creation date descending (newest first)
+          pending.sort(function(a, b) {
+            return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+          });
+
+          var limited = pending.slice(0, limit);
+
+          return jsonResult({
+            total: pending.length,
+            showing: limited.length,
+            requests: limited,
+          });
+        } catch (err: any) {
+          return errorResult(err.message || 'Failed to list pending requests.');
+        }
+      },
+    },
+    {
+      name: 'ent_wf_cancel',
+      label: 'Cancel Workflow Request',
+      description: 'Cancel a pending approval request. Only requests with status "pending" can be cancelled.',
+      category: 'utility',
+      risk: 'medium',
+      parameters: {
+        type: 'object',
+        properties: {
+          request_id: { type: 'string', description: 'The UUID of the workflow request to cancel.' },
+          reason: { type: 'string', description: 'Optional reason for cancellation.' },
+        },
+        required: ['request_id'],
+      },
+      execute: async function(_toolCallId, args) {
+        var params = args as Record<string, unknown>;
+        try {
+          var requestId = readStringParam(params, 'request_id', { required: true });
+          var reason = readStringParam(params, 'reason');
+
+          var store = await loadWorkflowStore(storePath);
+          var idx = store.requests.findIndex(function(r) { return r.id === requestId; });
+
+          if (idx === -1) {
+            return errorResult('Workflow request not found: ' + requestId);
+          }
+
+          var request = store.requests[idx];
+          if (request.status !== 'pending') {
+            return errorResult('Cannot cancel request with status "' + request.status + '". Only pending requests can be cancelled.');
+          }
+
+          var now = new Date().toISOString();
+          store.requests[idx] = Object.assign({}, request, {
+            status: 'cancelled' as WorkflowStatus,
+            updatedAt: now,
+            cancelReason: reason || undefined,
+          });
+
+          await saveWorkflowStore(storePath, store);
+          return jsonResult(store.requests[idx]);
+        } catch (err: any) {
+          return errorResult(err.message || 'Failed to cancel workflow request.');
+        }
+      },
+    },
+    {
+      name: 'ent_wf_remind',
+      label: 'Send Workflow Reminder',
+      description: 'Send a reminder about a pending approval request. Updates the lastRemindedAt timestamp and returns confirmation with request details.',
+      category: 'utility',
+      risk: 'low',
+      parameters: {
+        type: 'object',
+        properties: {
+          request_id: { type: 'string', description: 'The UUID of the workflow request to remind about.' },
+        },
+        required: ['request_id'],
+      },
+      execute: async function(_toolCallId, args) {
+        var params = args as Record<string, unknown>;
+        try {
+          var requestId = readStringParam(params, 'request_id', { required: true });
+
+          var store = await loadWorkflowStore(storePath);
+          var idx = store.requests.findIndex(function(r) { return r.id === requestId; });
+
+          if (idx === -1) {
+            return errorResult('Workflow request not found: ' + requestId);
+          }
+
+          var request = store.requests[idx];
+          if (request.status !== 'pending') {
+            return errorResult('Cannot remind for request with status "' + request.status + '". Only pending requests can receive reminders.');
+          }
+
+          var now = new Date().toISOString();
+          store.requests[idx] = Object.assign({}, request, {
+            lastRemindedAt: now,
+            updatedAt: now,
+          });
+
+          await saveWorkflowStore(storePath, store);
+
+          console.log('[AgenticMail] Reminder sent for workflow request "' + request.title + '" (' + requestId + ') to approvers: ' + request.approvers.join(', '));
+
+          return jsonResult({
+            reminded: true,
+            request_id: requestId,
+            title: request.title,
+            approvers: request.approvers,
+            lastRemindedAt: now,
+          });
+        } catch (err: any) {
+          return errorResult(err.message || 'Failed to send workflow reminder.');
+        }
+      },
+    },
+  ];
+}

package/src/agent-tools/tools/glob.ts

@@ -0,0 +1,129 @@
+/**
+ * AgenticMail Agent Tools — Glob
+ *
+ * Find files matching glob patterns with path sandbox enforcement,
+ * depth limiting, and timeout protection.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AnyAgentTool, ToolCreationOptions } from '../types.js';
+import { readStringParam, readNumberParam, textResult } from '../common.js';
+import type { PathSandbox } from '../security.js';
+
+const DEFAULT_MAX_RESULTS = 200;
+const DEFAULT_MAX_DEPTH = 20;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+// Fallback glob implementation using recursive readdir
+async function simpleGlob(
+  pattern: string,
+  cwd: string,
+  opts: { maxDepth: number; deadline: number },
+): Promise<string[]> {
+  var results: string[] = [];
+
+  // Convert simple glob pattern to regex
+  var regexStr = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*/g, '{{GLOBSTAR}}')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]')
+    .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+  var regex = new RegExp('^' + regexStr + '$');
+
+  async function walk(dir: string, prefix: string, depth: number) {
+    // Depth limit
+    if (depth > opts.maxDepth) return;
+    // Timeout check
+    if (Date.now() > opts.deadline) return;
+
+    try {
+      var entries = await fs.readdir(dir, { withFileTypes: true });
+      for (var entry of entries) {
+        if (Date.now() > opts.deadline) return;
+        if (entry.name.startsWith('.') && !pattern.startsWith('.')) continue;
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        var relPath = prefix ? prefix + '/' + entry.name : entry.name;
+        if (entry.isDirectory()) {
+          await walk(path.join(dir, entry.name), relPath, depth + 1);
+        } else if (regex.test(relPath)) {
+          results.push(relPath);
+        }
+      }
+    } catch { /* skip unreadable dirs */ }
+  }
+
+  await walk(cwd, '', 0);
+  return results.sort();
+}
+
+export function createGlobTool(options?: ToolCreationOptions & { pathSandbox?: PathSandbox }): AnyAgentTool {
+  var sandbox = options?.pathSandbox;
+
+  return {
+    name: 'glob',
+    label: 'Find Files',
+    description: 'Find files matching a glob pattern. Supports ** for recursive matching, * for single directory wildcards. Returns matching file paths.',
+    category: 'search',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Glob pattern (e.g. "**/*.ts", "src/**/*.js").' },
+        path: { type: 'string', description: 'Directory to search in. Defaults to workspace root.' },
+        max_results: { type: 'number', description: 'Maximum results to return (default 200).' },
+      },
+      required: ['pattern'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var pattern = readStringParam(params, 'pattern', { required: true });
+      var searchPath = readStringParam(params, 'path');
+      var maxResults = readNumberParam(params, 'max_results', { integer: true }) ?? DEFAULT_MAX_RESULTS;
+
+      var cwd = searchPath || options?.workspaceDir || process.cwd();
+      if (!path.isAbsolute(cwd) && options?.workspaceDir) {
+        cwd = path.resolve(options.workspaceDir, cwd);
+      }
+
+      // Path sandbox enforcement — validate the search directory
+      if (sandbox) {
+        try {
+          sandbox.validate(cwd);
+        } catch (err: any) {
+          return textResult('Access denied: ' + (err.message || 'path blocked by security policy'));
+        }
+      }
+
+      try {
+        var deadline = Date.now() + DEFAULT_TIMEOUT_MS;
+        var results = await simpleGlob(pattern, cwd, {
+          maxDepth: DEFAULT_MAX_DEPTH,
+          deadline,
+        });
+        var limited = results.slice(0, maxResults);
+        var truncated = results.length > maxResults;
+        var timedOut = Date.now() > deadline;
+
+        if (limited.length === 0) {
+          var msg = 'No files matching "' + pattern + '" found in ' + cwd;
+          if (timedOut) msg += ' (search timed out)';
+          return textResult(msg);
+        }
+
+        var fullPaths = limited.map(function(r) { return path.join(cwd, r); });
+        var output = fullPaths.join('\n');
+        if (truncated) {
+          output += '\n\n(' + results.length + ' total matches, showing first ' + maxResults + ')';
+        }
+        if (timedOut) {
+          output += '\n(search timed out, results may be incomplete)';
+        }
+        return textResult(output);
+      } catch (err: any) {
+        return textResult('Glob error: ' + (err.message || 'unknown error'));
+      }
+    },
+  };
+}

package/src/agent-tools/tools/grep.ts

@@ -0,0 +1,178 @@
+/**
+ * AgenticMail Agent Tools — Grep
+ *
+ * Search file contents using regular expressions with path sandbox enforcement,
+ * shell-safe ripgrep execution, and timeout protection.
+ * Powered by ripgrep when available, with a Node.js fallback.
+ */
+
+import { exec } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AnyAgentTool, ToolCreationOptions } from '../types.js';
+import { readStringParam, readNumberParam, readBooleanParam, textResult } from '../common.js';
+import type { PathSandbox } from '../security.js';
+import { shellEscape } from '../security.js';
+
+const DEFAULT_MAX_RESULTS = 100;
+const DEFAULT_CONTEXT_LINES = 0;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const NODE_SEARCH_DEADLINE_MS = 15_000;
+
+async function hasRipgrep(): Promise<boolean> {
+  return new Promise(function(resolve) {
+    exec('rg --version', { timeout: 3000 }, function(error) { resolve(!error); });
+  });
+}
+
+async function ripgrepSearch(params: {
+  pattern: string;
+  searchPath: string;
+  glob?: string;
+  maxResults: number;
+  contextLines: number;
+  caseInsensitive: boolean;
+  filesOnly: boolean;
+}): Promise<string> {
+  var args = ['rg'];
+  if (params.caseInsensitive) args.push('-i');
+  if (params.filesOnly) {
+    args.push('-l');
+  } else {
+    args.push('-n');
+    if (params.contextLines > 0) args.push('-C', String(params.contextLines));
+  }
+  if (params.glob) args.push('--glob', shellEscape(params.glob));
+  args.push('-m', String(params.maxResults));
+  // Use -- to separate pattern from paths, and shell-escape the pattern
+  args.push('--', shellEscape(params.pattern), shellEscape(params.searchPath));
+
+  return new Promise(function(resolve) {
+    exec(args.join(' '), { maxBuffer: 1_000_000, timeout: DEFAULT_TIMEOUT_MS }, function(error, stdout) {
+      resolve(stdout || '');
+    });
+  });
+}
+
+async function nodeSearch(params: {
+  pattern: string;
+  searchPath: string;
+  glob?: string;
+  maxResults: number;
+  contextLines: number;
+  caseInsensitive: boolean;
+  filesOnly: boolean;
+}): Promise<string> {
+  var flags = params.caseInsensitive ? 'gi' : 'g';
+  var regex: RegExp;
+  try { regex = new RegExp(params.pattern, flags); }
+  catch { return 'Invalid regex pattern: ' + params.pattern; }
+
+  var results: string[] = [];
+  var matchCount = 0;
+  var deadline = Date.now() + NODE_SEARCH_DEADLINE_MS;
+
+  async function searchDir(dir: string) {
+    if (matchCount >= params.maxResults) return;
+    if (Date.now() > deadline) return;
+    try {
+      var entries = await fs.readdir(dir, { withFileTypes: true });
+      for (var entry of entries) {
+        if (matchCount >= params.maxResults || Date.now() > deadline) return;
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+        var fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await searchDir(fullPath);
+        } else {
+          // Simple glob check
+          if (params.glob) {
+            var ext = '*' + path.extname(entry.name);
+            if (!params.glob.includes(ext) && !params.glob.includes('*.*')) continue;
+          }
+          try {
+            var content = await fs.readFile(fullPath, 'utf-8');
+            var lines = content.split('\n');
+            for (var i = 0; i < lines.length; i++) {
+              if (matchCount >= params.maxResults) break;
+              if (regex.test(lines[i])) {
+                regex.lastIndex = 0;
+                if (params.filesOnly) {
+                  results.push(fullPath);
+                  break;
+                }
+                results.push(fullPath + ':' + (i + 1) + ':' + lines[i]);
+                matchCount++;
+              }
+            }
+          } catch { /* skip unreadable */ }
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  await searchDir(params.searchPath);
+  if (Date.now() > deadline) {
+    results.push('\n(search timed out, results may be incomplete)');
+  }
+  return results.join('\n');
+}
+
+export function createGrepTool(options?: ToolCreationOptions & { pathSandbox?: PathSandbox }): AnyAgentTool {
+  var sandbox = options?.pathSandbox;
+
+  return {
+    name: 'grep',
+    label: 'Search Content',
+    description: 'Search file contents using regular expressions. Uses ripgrep when available for speed. Returns matching lines with file paths and line numbers.',
+    category: 'search',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Regular expression pattern to search for.' },
+        path: { type: 'string', description: 'File or directory to search in.' },
+        glob: { type: 'string', description: 'Glob pattern to filter files (e.g. "*.ts").' },
+        max_results: { type: 'number', description: 'Maximum results to return.' },
+        context: { type: 'number', description: 'Lines of context around matches.' },
+        case_insensitive: { type: 'string', description: 'Set to "true" for case-insensitive search.' },
+        files_only: { type: 'string', description: 'Set to "true" to return only file paths.' },
+      },
+      required: ['pattern'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var pattern = readStringParam(params, 'pattern', { required: true });
+      var searchPath = readStringParam(params, 'path') || options?.workspaceDir || process.cwd();
+      var glob = readStringParam(params, 'glob');
+      var maxResults = readNumberParam(params, 'max_results', { integer: true }) ?? DEFAULT_MAX_RESULTS;
+      var contextLines = readNumberParam(params, 'context', { integer: true }) ?? DEFAULT_CONTEXT_LINES;
+      var caseInsensitive = readBooleanParam(params, 'case_insensitive', false);
+      var filesOnly = readBooleanParam(params, 'files_only', false);
+
+      if (!path.isAbsolute(searchPath) && options?.workspaceDir) {
+        searchPath = path.resolve(options.workspaceDir, searchPath);
+      }
+
+      // Path sandbox enforcement
+      if (sandbox) {
+        try {
+          sandbox.validate(searchPath);
+        } catch (err: any) {
+          return textResult('Access denied: ' + (err.message || 'path blocked by security policy'));
+        }
+      }
+
+      var searchParams = { pattern, searchPath, glob, maxResults, contextLines, caseInsensitive, filesOnly };
+
+      var useRg = await hasRipgrep();
+      var output = useRg
+        ? await ripgrepSearch(searchParams)
+        : await nodeSearch(searchParams);
+
+      if (!output.trim()) {
+        return textResult('No matches found for "' + pattern + '" in ' + searchPath);
+      }
+      return textResult(output);
+    },
+  };
+}