@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,194 @@
+/**
+ * AgenticMail Agent Tools — Memory
+ *
+ * Persistent memory/notes system for agents with size limits,
+ * atomic writes, and entry count protection.
+ */
+
+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, jsonResult, textResult, errorResult } from '../common.js';
+
+const MEMORY_ACTIONS = ['set', 'get', 'search', 'list', 'delete'] as const;
+type MemoryAction = (typeof MEMORY_ACTIONS)[number];
+
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_MAX_VALUE_SIZE = 100 * 1024;    // 100KB per entry
+const DEFAULT_MAX_STORE_SIZE = 10 * 1024 * 1024; // 10MB total
+
+type MemoryEntry = {
+  key: string;
+  value: string;
+  tags: string[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+type MemoryStore = {
+  entries: Record<string, MemoryEntry>;
+};
+
+async function loadMemoryStore(storePath: string): Promise<MemoryStore> {
+  try {
+    var content = await fs.readFile(storePath, 'utf-8');
+    return JSON.parse(content) as MemoryStore;
+  } catch {
+    return { entries: {} };
+  }
+}
+
+async function saveMemoryStore(storePath: string, store: MemoryStore): Promise<void> {
+  var dir = path.dirname(storePath);
+  await fs.mkdir(dir, { recursive: true });
+  var data = JSON.stringify(store, null, 2);
+
+  // Check total store size
+  var storeSize = Buffer.byteLength(data, 'utf-8');
+  if (storeSize > DEFAULT_MAX_STORE_SIZE) {
+    throw new Error('Memory store exceeds maximum size (' + Math.round(storeSize / 1024 / 1024) + 'MB). Delete some entries first.');
+  }
+
+  // Atomic write: write to temp file then rename
+  var tmpPath = storePath + '.tmp.' + crypto.randomBytes(4).toString('hex');
+  try {
+    await fs.writeFile(tmpPath, data, 'utf-8');
+    await fs.rename(tmpPath, storePath);
+  } catch (err) {
+    // Cleanup temp file on failure
+    try { await fs.unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+function searchEntries(
+  entries: Record<string, MemoryEntry>,
+  query: string,
+  limit: number,
+): MemoryEntry[] {
+  var queryLower = query.toLowerCase();
+  var scored: Array<{ entry: MemoryEntry; score: number }> = [];
+
+  for (var entry of Object.values(entries)) {
+    var score = 0;
+    if (entry.key.toLowerCase().includes(queryLower)) score += 10;
+    if (entry.value.toLowerCase().includes(queryLower)) score += 5;
+    for (var tag of entry.tags) {
+      if (tag.toLowerCase().includes(queryLower)) score += 3;
+    }
+    if (score > 0) scored.push({ entry, score });
+  }
+
+  scored.sort(function(a, b) { return b.score - a.score; });
+  return scored.slice(0, limit).map(function(s) { return s.entry; });
+}
+
+export function createMemoryTool(options?: ToolCreationOptions): AnyAgentTool | null {
+  var memoryConfig = options?.config?.memory;
+  if (memoryConfig?.enabled === false) return null;
+
+  var storePath = path.join(
+    options?.workspaceDir || process.cwd(),
+    '.agenticmail',
+    'agent-memory.json',
+  );
+
+  return {
+    name: 'memory',
+    label: 'Memory',
+    description: 'Persistent memory for storing and retrieving notes, facts, and context across conversations. Supports set, get, search, list, and delete operations.',
+    category: 'memory',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          description: 'Action: set, get, search, list, or delete.',
+          enum: MEMORY_ACTIONS as unknown as string[],
+        },
+        key: { type: 'string', description: 'Memory key (for set/get/delete).' },
+        value: { type: 'string', description: 'Value to store (for set).' },
+        tags: { type: 'string', description: 'Comma-separated tags (for set).' },
+        query: { type: 'string', description: 'Search query (for search).' },
+        limit: { type: 'number', description: 'Max results for search/list.' },
+      },
+      required: ['action'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var action = readStringParam(params, 'action', { required: true }) as MemoryAction;
+      var store = await loadMemoryStore(storePath);
+
+      switch (action) {
+        case 'set': {
+          var key = readStringParam(params, 'key', { required: true });
+          var value = readStringParam(params, 'value', { required: true, trim: false });
+          var tagsRaw = readStringParam(params, 'tags') || '';
+          var tags = tagsRaw.split(',').map(function(t) { return t.trim(); }).filter(Boolean);
+          var now = new Date().toISOString();
+
+          // Value size limit
+          var valueSize = Buffer.byteLength(value, 'utf-8');
+          if (valueSize > DEFAULT_MAX_VALUE_SIZE) {
+            return errorResult('Value too large: ' + Math.round(valueSize / 1024) + 'KB. Maximum is 100KB per entry.');
+          }
+
+          // Entry count limit (only for new entries)
+          var existing = store.entries[key];
+          if (!existing && Object.keys(store.entries).length >= DEFAULT_MAX_ENTRIES) {
+            return errorResult('Memory store full: ' + DEFAULT_MAX_ENTRIES + ' entries maximum. Delete some entries first.');
+          }
+
+          store.entries[key] = {
+            key,
+            value,
+            tags,
+            createdAt: existing?.createdAt || now,
+            updatedAt: now,
+          };
+          await saveMemoryStore(storePath, store);
+          return textResult('Stored memory: ' + key);
+        }
+
+        case 'get': {
+          var key = readStringParam(params, 'key', { required: true });
+          var entry = store.entries[key];
+          if (!entry) return textResult('Memory not found: ' + key);
+          return jsonResult(entry);
+        }
+
+        case 'search': {
+          var query = readStringParam(params, 'query', { required: true });
+          var limit = readNumberParam(params, 'limit', { integer: true }) ?? 10;
+          var results = searchEntries(store.entries, query, limit);
+          if (results.length === 0) return textResult('No memories matching: ' + query);
+          return jsonResult({ count: results.length, results });
+        }
+
+        case 'list': {
+          var limit = readNumberParam(params, 'limit', { integer: true }) ?? 20;
+          var keys = Object.keys(store.entries);
+          var limited = keys.slice(0, limit);
+          var entries = limited.map(function(k) {
+            var e = store.entries[k];
+            return { key: e.key, tags: e.tags, updatedAt: e.updatedAt };
+          });
+          return jsonResult({ count: keys.length, showing: limited.length, entries });
+        }
+
+        case 'delete': {
+          var key = readStringParam(params, 'key', { required: true });
+          if (!store.entries[key]) return textResult('Memory not found: ' + key);
+          delete store.entries[key];
+          await saveMemoryStore(storePath, store);
+          return textResult('Deleted memory: ' + key);
+        }
+
+        default:
+          return errorResult('Unknown memory action: ' + action);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,160 @@
+/**
+ * AgenticMail Agent Tools — Read
+ *
+ * Read file contents with line numbering, offset/limit support,
+ * image detection, binary file handling, and path sandbox enforcement.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AnyAgentTool, ToolCreationOptions } from '../types.js';
+import { readStringParam, readNumberParam, textResult, errorResult } from '../common.js';
+import type { PathSandbox } from '../security.js';
+
+const DEFAULT_MAX_LINES = 2000;
+const DEFAULT_MAX_LINE_LENGTH = 2000;
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+
+function numberLines(content: string, startLine: number): string {
+  var lines = content.split('\n');
+  var width = String(startLine + lines.length - 1).length;
+  return lines
+    .map(function(line, i) {
+      var num = String(startLine + i).padStart(width, ' ');
+      var truncated = line.length > DEFAULT_MAX_LINE_LENGTH
+        ? line.slice(0, DEFAULT_MAX_LINE_LENGTH) + '... (truncated)'
+        : line;
+      return num + '\t' + truncated;
+    })
+    .join('\n');
+}
+
+async function detectBinary(filePath: string): Promise<boolean> {
+  try {
+    var fd = await fs.open(filePath, 'r');
+    try {
+      var buf = Buffer.alloc(512);
+      var result = await fd.read(buf, 0, 512, 0);
+      for (var i = 0; i < result.bytesRead; i++) {
+        if (buf[i] === 0) return true;
+      }
+      return false;
+    } finally {
+      await fd.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
+function isImagePath(filePath: string): boolean {
+  var ext = path.extname(filePath).toLowerCase();
+  return ['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp', '.svg', '.ico'].includes(ext);
+}
+
+export function createReadTool(options?: ToolCreationOptions & { pathSandbox?: PathSandbox }): AnyAgentTool {
+  var sandbox = options?.pathSandbox;
+
+  return {
+    name: 'read',
+    label: 'Read File',
+    description: 'Read a file from the filesystem. Returns content with line numbers. Supports offset and limit for large files. Can read images and detect binary files.',
+    category: 'file',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the file to read.' },
+        offset: { type: 'number', description: 'Line number to start reading from (1-based).' },
+        limit: { type: 'number', description: 'Number of lines to read.' },
+      },
+      required: ['file_path'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var offset = readNumberParam(params, 'offset', { integer: true });
+      var limit = readNumberParam(params, 'limit', { integer: true });
+
+      // Resolve path relative to workspace
+      if (!path.isAbsolute(filePath) && options?.workspaceDir) {
+        filePath = path.resolve(options.workspaceDir, filePath);
+      }
+
+      // Path sandbox enforcement
+      if (sandbox) {
+        try {
+          sandbox.validate(filePath);
+        } catch (err: any) {
+          return errorResult('Access denied: ' + (err.message || 'path blocked by security policy'));
+        }
+      }
+
+      try {
+        var stat = await fs.stat(filePath);
+        if (stat.isDirectory()) {
+          return errorResult(filePath + ' is a directory. Use the bash tool with ls to list directory contents.');
+        }
+
+        // File size limit to prevent memory exhaustion
+        if (stat.size > DEFAULT_MAX_FILE_SIZE) {
+          return errorResult('File too large: ' + filePath + ' (' + Math.round(stat.size / 1024 / 1024) + 'MB). Maximum is 10MB.');
+        }
+      } catch (err: any) {
+        return errorResult('File not found: ' + filePath);
+      }
+
+      // Image files
+      if (isImagePath(filePath)) {
+        try {
+          var buf = await fs.readFile(filePath);
+          var ext = path.extname(filePath).toLowerCase();
+          var mimeMap: Record<string, string> = {
+            '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif', '.bmp': 'image/bmp', '.webp': 'image/webp',
+            '.svg': 'image/svg+xml', '.ico': 'image/x-icon',
+          };
+          return {
+            content: [
+              { type: 'text', text: 'Image: ' + filePath },
+              { type: 'image', data: buf.toString('base64'), mimeType: mimeMap[ext] || 'image/png' },
+            ],
+          };
+        } catch {
+          return errorResult('Failed to read image: ' + filePath);
+        }
+      }
+
+      // Binary detection
+      if (await detectBinary(filePath)) {
+        var size = stat.size;
+        return textResult('Binary file: ' + filePath + ' (' + size + ' bytes). Cannot display binary content.');
+      }
+
+      // Text files
+      try {
+        var content = await fs.readFile(filePath, 'utf-8');
+        var lines = content.split('\n');
+        var totalLines = lines.length;
+
+        var startLine = offset && offset > 0 ? offset : 1;
+        var maxLines = limit && limit > 0 ? limit : DEFAULT_MAX_LINES;
+
+        var startIdx = startLine - 1;
+        var endIdx = Math.min(startIdx + maxLines, totalLines);
+        var selectedLines = lines.slice(startIdx, endIdx);
+        var selected = selectedLines.join('\n');
+
+        var numbered = numberLines(selected, startLine);
+        var header = '';
+        if (startIdx > 0 || endIdx < totalLines) {
+          header = '(Showing lines ' + startLine + '-' + (startLine + selectedLines.length - 1) + ' of ' + totalLines + ')\n';
+        }
+
+        return textResult(header + numbered);
+      } catch (err: any) {
+        return errorResult('Failed to read file: ' + (err.message || filePath));
+      }
+    },
+  };
+}

package/src/agent-tools/tools/web-fetch-utils.ts

@@ -0,0 +1,202 @@
+/**
+ * AgenticMail Agent Tools — Web Fetch Utilities
+ *
+ * HTML to markdown conversion, readability extraction, text truncation.
+ */
+
+export type ExtractMode = 'markdown' | 'text';
+
+const READABILITY_MAX_HTML_CHARS = 1_000_000;
+const READABILITY_MAX_ESTIMATED_NESTING_DEPTH = 3_000;
+
+let readabilityDepsPromise:
+  | Promise<{
+      Readability: typeof import('@mozilla/readability').Readability;
+      parseHTML: typeof import('linkedom').parseHTML;
+    }>
+  | undefined;
+
+async function loadReadabilityDeps(): Promise<{
+  Readability: typeof import('@mozilla/readability').Readability;
+  parseHTML: typeof import('linkedom').parseHTML;
+}> {
+  if (!readabilityDepsPromise) {
+    readabilityDepsPromise = Promise.all([import('@mozilla/readability'), import('linkedom')]).then(
+      function([readability, linkedom]) {
+        return {
+          Readability: readability.Readability,
+          parseHTML: linkedom.parseHTML,
+        };
+      },
+    );
+  }
+  try {
+    return await readabilityDepsPromise;
+  } catch (error) {
+    readabilityDepsPromise = undefined;
+    throw error;
+  }
+}
+
+function decodeEntities(value: string): string {
+  return value
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&#x([0-9a-f]+);/gi, function(_, hex) { return String.fromCharCode(Number.parseInt(hex, 16)); })
+    .replace(/&#(\d+);/gi, function(_, dec) { return String.fromCharCode(Number.parseInt(dec, 10)); });
+}
+
+function stripTags(value: string): string {
+  return decodeEntities(value.replace(/<[^>]+>/g, ''));
+}
+
+function normalizeWhitespace(value: string): string {
+  return value
+    .replace(/\r/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+export function htmlToMarkdown(html: string): { text: string; title?: string } {
+  var titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  var title = titleMatch ? normalizeWhitespace(stripTags(titleMatch[1])) : undefined;
+  var text = html
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, '');
+  text = text.replace(/<a\s+[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, function(_, href, body) {
+    var label = normalizeWhitespace(stripTags(body));
+    if (!label) return href;
+    return '[' + label + '](' + href + ')';
+  });
+  text = text.replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, function(_, level, body) {
+    var prefix = '#'.repeat(Math.max(1, Math.min(6, Number.parseInt(level, 10))));
+    var label = normalizeWhitespace(stripTags(body));
+    return '\n' + prefix + ' ' + label + '\n';
+  });
+  text = text.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, function(_, body) {
+    var label = normalizeWhitespace(stripTags(body));
+    return label ? '\n- ' + label : '';
+  });
+  text = text
+    .replace(/<(br|hr)\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|section|article|header|footer|table|tr|ul|ol)>/gi, '\n');
+  text = stripTags(text);
+  text = normalizeWhitespace(text);
+  return { text, title };
+}
+
+export function markdownToText(markdown: string): string {
+  var text = markdown;
+  text = text.replace(/!\[[^\]]*]\([^)]+\)/g, '');
+  text = text.replace(/\[([^\]]+)]\([^)]+\)/g, '$1');
+  text = text.replace(/```[\s\S]*?```/g, function(block) {
+    return block.replace(/```[^\n]*\n?/g, '').replace(/```/g, '');
+  });
+  text = text.replace(/`([^`]+)`/g, '$1');
+  text = text.replace(/^#{1,6}\s+/gm, '');
+  text = text.replace(/^\s*[-*+]\s+/gm, '');
+  text = text.replace(/^\s*\d+\.\s+/gm, '');
+  return normalizeWhitespace(text);
+}
+
+export function truncateText(
+  value: string,
+  maxChars: number,
+): { text: string; truncated: boolean } {
+  if (value.length <= maxChars) return { text: value, truncated: false };
+  return { text: value.slice(0, maxChars), truncated: true };
+}
+
+function exceedsEstimatedHtmlNestingDepth(html: string, maxDepth: number): boolean {
+  var voidTags = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+  ]);
+
+  var depth = 0;
+  var len = html.length;
+  for (var i = 0; i < len; i++) {
+    if (html.charCodeAt(i) !== 60) continue; // '<'
+    var next = html.charCodeAt(i + 1);
+    if (next === 33 || next === 63) continue; // <! or <?
+
+    var j = i + 1;
+    var closing = false;
+    if (html.charCodeAt(j) === 47) { closing = true; j += 1; }
+    while (j < len && html.charCodeAt(j) <= 32) j += 1;
+
+    var nameStart = j;
+    while (j < len) {
+      var c = html.charCodeAt(j);
+      var isNameChar = (c >= 65 && c <= 90) || (c >= 97 && c <= 122) ||
+        (c >= 48 && c <= 57) || c === 58 || c === 45;
+      if (!isNameChar) break;
+      j += 1;
+    }
+
+    var tagName = html.slice(nameStart, j).toLowerCase();
+    if (!tagName) continue;
+
+    if (closing) { depth = Math.max(0, depth - 1); continue; }
+    if (voidTags.has(tagName)) continue;
+
+    var selfClosing = false;
+    for (var k = j; k < len && k < j + 200; k++) {
+      var ch = html.charCodeAt(k);
+      if (ch === 62) {
+        if (html.charCodeAt(k - 1) === 47) selfClosing = true;
+        break;
+      }
+    }
+    if (selfClosing) continue;
+
+    depth += 1;
+    if (depth > maxDepth) return true;
+  }
+  return false;
+}
+
+export async function extractReadableContent(params: {
+  html: string;
+  url: string;
+  extractMode: ExtractMode;
+}): Promise<{ text: string; title?: string } | null> {
+  var fallback = function(): { text: string; title?: string } {
+    var rendered = htmlToMarkdown(params.html);
+    if (params.extractMode === 'text') {
+      var text = markdownToText(rendered.text) || normalizeWhitespace(stripTags(params.html));
+      return { text, title: rendered.title };
+    }
+    return rendered;
+  };
+  if (
+    params.html.length > READABILITY_MAX_HTML_CHARS ||
+    exceedsEstimatedHtmlNestingDepth(params.html, READABILITY_MAX_ESTIMATED_NESTING_DEPTH)
+  ) {
+    return fallback();
+  }
+  try {
+    var deps = await loadReadabilityDeps();
+    var doc = deps.parseHTML(params.html);
+    try { (doc.document as { baseURI?: string }).baseURI = params.url; } catch { /* ignore */ }
+    var reader = new deps.Readability(doc.document, { charThreshold: 0 });
+    var parsed = reader.parse();
+    if (!parsed?.content) return fallback();
+    var title = parsed.title || undefined;
+    if (params.extractMode === 'text') {
+      var text = normalizeWhitespace(parsed.textContent ?? '');
+      return text ? { text, title } : fallback();
+    }
+    var rendered = htmlToMarkdown(parsed.content);
+    return { text: rendered.text, title: title ?? rendered.title };
+  } catch {
+    return fallback();
+  }
+}