@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,825 @@
+/**
+ * AgenticMail Agent Tools — Enterprise Spreadsheet
+ *
+ * CSV/TSV spreadsheet tools for AI agents.
+ * Read, write, filter, aggregate, transform, merge, pivot,
+ * and convert tabular data using built-in Node.js APIs.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AnyAgentTool, ToolCreationOptions } from '../types.js';
+import { readStringParam, readNumberParam, jsonResult, textResult, errorResult } from '../common.js';
+
+// --- CSV Parsing / Formatting Helpers ---
+
+function parseCSV(content: string, delimiter?: string): { headers: string[]; rows: Record<string, string>[] } {
+  var sep = delimiter || ',';
+  var lines = content.split(/\r?\n/).filter(function(line) { return line.trim() !== ''; });
+  if (lines.length === 0) return { headers: [], rows: [] };
+
+  function parseLine(line: string): string[] {
+    var fields: string[] = [];
+    var current = '';
+    var inQuotes = false;
+    for (var i = 0; i < line.length; i++) {
+      var ch = line[i];
+      if (inQuotes) {
+        if (ch === '"') {
+          if (i + 1 < line.length && line[i + 1] === '"') {
+            current += '"';
+            i++;
+          } else {
+            inQuotes = false;
+          }
+        } else {
+          current += ch;
+        }
+      } else {
+        if (ch === '"') {
+          inQuotes = true;
+        } else if (ch === sep) {
+          fields.push(current);
+          current = '';
+        } else {
+          current += ch;
+        }
+      }
+    }
+    fields.push(current);
+    return fields;
+  }
+
+  var headers = parseLine(lines[0]).map(function(h) { return h.trim(); });
+  var rows: Record<string, string>[] = [];
+  for (var i = 1; i < lines.length; i++) {
+    var fields = parseLine(lines[i]);
+    var row: Record<string, string> = {};
+    for (var j = 0; j < headers.length; j++) {
+      row[headers[j]] = j < fields.length ? fields[j] : '';
+    }
+    rows.push(row);
+  }
+  return { headers: headers, rows: rows };
+}
+
+function formatCSV(rows: Record<string, string>[], headers: string[], delimiter?: string): string {
+  var sep = delimiter || ',';
+
+  function escapeField(value: string): string {
+    if (value.indexOf(sep) >= 0 || value.indexOf('"') >= 0 || value.indexOf('\n') >= 0) {
+      return '"' + value.replace(/"/g, '""') + '"';
+    }
+    return value;
+  }
+
+  var lines = [headers.map(escapeField).join(sep)];
+  for (var row of rows) {
+    var fields = headers.map(function(h) { return escapeField(row[h] ?? ''); });
+    lines.push(fields.join(sep));
+  }
+  return lines.join('\n') + '\n';
+}
+
+function detectDelimiter(filePath: string): string {
+  var ext = path.extname(filePath).toLowerCase();
+  if (ext === '.tsv' || ext === '.tab') return '\t';
+  return ',';
+}
+
+async function readSpreadsheet(filePath: string, workspaceDir?: string): Promise<{ headers: string[]; rows: Record<string, string>[]; resolvedPath: string }> {
+  var resolvedPath = filePath;
+  if (!path.isAbsolute(resolvedPath) && workspaceDir) {
+    resolvedPath = path.resolve(workspaceDir, resolvedPath);
+  }
+  var content = await fs.readFile(resolvedPath, 'utf-8');
+  var delimiter = detectDelimiter(resolvedPath);
+  var result = parseCSV(content, delimiter);
+  return { headers: result.headers, rows: result.rows, resolvedPath: resolvedPath };
+}
+
+export function createSpreadsheetTools(options?: ToolCreationOptions): AnyAgentTool[] {
+
+  var entSheetRead: AnyAgentTool = {
+    name: 'ent_sheet_read',
+    label: 'Read Spreadsheet',
+    description: 'Read a CSV or TSV file and return its contents as a JSON table with headers and rows. Supports offset and limit for large files.',
+    category: 'file',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to the CSV/TSV file.' },
+        offset: { type: 'number', description: 'Row offset to start from (0-based, default 0).' },
+        limit: { type: 'number', description: 'Maximum number of rows to return (default 100).' },
+      },
+      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 }) ?? 0;
+      var limit = readNumberParam(params, 'limit', { integer: true }) ?? 100;
+
+      try {
+        var data = await readSpreadsheet(filePath, options?.workspaceDir);
+        var sliced = data.rows.slice(offset, offset + limit);
+        return jsonResult({
+          file: data.resolvedPath,
+          headers: data.headers,
+          rows: sliced,
+          totalRows: data.rows.length,
+          showing: sliced.length,
+          offset: offset,
+        });
+      } catch (err: any) {
+        return errorResult('Failed to read spreadsheet: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetWrite: AnyAgentTool = {
+    name: 'ent_sheet_write',
+    label: 'Write Spreadsheet',
+    description: 'Write rows to a CSV or TSV file. Creates or overwrites the file. Accepts an array of row objects and optional headers.',
+    category: 'file',
+    risk: 'medium',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to write the CSV/TSV file.' },
+        rows: { type: 'string', description: 'JSON array of row objects to write.' },
+        headers: { type: 'string', description: 'Comma-separated list of column headers (optional, inferred from first row if omitted).' },
+      },
+      required: ['file_path', 'rows'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var rowsRaw = readStringParam(params, 'rows', { required: true, trim: false });
+      var headersStr = readStringParam(params, 'headers');
+
+      if (!path.isAbsolute(filePath) && options?.workspaceDir) {
+        filePath = path.resolve(options.workspaceDir, filePath);
+      }
+
+      try {
+        var rows: Record<string, string>[];
+        try {
+          rows = JSON.parse(rowsRaw);
+        } catch {
+          return errorResult('Invalid JSON for rows parameter. Expected an array of objects.');
+        }
+
+        if (!Array.isArray(rows) || rows.length === 0) {
+          return errorResult('Rows must be a non-empty JSON array of objects.');
+        }
+
+        var headers: string[];
+        if (headersStr) {
+          headers = headersStr.split(',').map(function(h) { return h.trim(); });
+        } else {
+          headers = Object.keys(rows[0]);
+        }
+
+        var delimiter = detectDelimiter(filePath);
+        var content = formatCSV(rows, headers, delimiter);
+        var dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(filePath, content, 'utf-8');
+        return textResult('Wrote ' + rows.length + ' rows (' + headers.length + ' columns) to ' + filePath);
+      } catch (err: any) {
+        return errorResult('Failed to write spreadsheet: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetFilter: AnyAgentTool = {
+    name: 'ent_sheet_filter',
+    label: 'Filter Spreadsheet',
+    description: 'Filter rows in a CSV/TSV file by a column condition. Supports operators: equals, contains, gt, lt, gte, lte, regex, not_equals.',
+    category: 'utility',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to the CSV/TSV file.' },
+        column: { type: 'string', description: 'Column name to filter on.' },
+        operator: { type: 'string', description: 'Comparison operator.', enum: ['equals', 'not_equals', 'contains', 'gt', 'lt', 'gte', 'lte', 'regex'] },
+        value: { type: 'string', description: 'Value to compare against.' },
+        limit: { type: 'number', description: 'Maximum matching rows to return (default 100).' },
+      },
+      required: ['file_path', 'column', 'operator', 'value'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var column = readStringParam(params, 'column', { required: true });
+      var operator = readStringParam(params, 'operator', { required: true });
+      var value = readStringParam(params, 'value', { required: true, allowEmpty: true });
+      var limit = readNumberParam(params, 'limit', { integer: true }) ?? 100;
+
+      try {
+        var data = await readSpreadsheet(filePath, options?.workspaceDir);
+        if (data.headers.indexOf(column) === -1) {
+          return errorResult('Column not found: ' + column + '. Available: ' + data.headers.join(', '));
+        }
+
+        var matched = data.rows.filter(function(row) {
+          var cellValue = row[column] ?? '';
+          var numCell = parseFloat(cellValue);
+          var numValue = parseFloat(value);
+
+          switch (operator) {
+            case 'equals': return cellValue === value;
+            case 'not_equals': return cellValue !== value;
+            case 'contains': return cellValue.toLowerCase().indexOf(value.toLowerCase()) >= 0;
+            case 'gt': return !isNaN(numCell) && !isNaN(numValue) && numCell > numValue;
+            case 'lt': return !isNaN(numCell) && !isNaN(numValue) && numCell < numValue;
+            case 'gte': return !isNaN(numCell) && !isNaN(numValue) && numCell >= numValue;
+            case 'lte': return !isNaN(numCell) && !isNaN(numValue) && numCell <= numValue;
+            case 'regex': {
+              try { return new RegExp(value, 'i').test(cellValue); } catch { return false; }
+            }
+            default: return false;
+          }
+        });
+
+        var limited = matched.slice(0, limit);
+        return jsonResult({
+          headers: data.headers,
+          rows: limited,
+          matchedCount: matched.length,
+          showing: limited.length,
+          totalRows: data.rows.length,
+        });
+      } catch (err: any) {
+        return errorResult('Filter failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetAggregate: AnyAgentTool = {
+    name: 'ent_sheet_aggregate',
+    label: 'Aggregate Spreadsheet',
+    description: 'Compute aggregations on a CSV/TSV column: sum, avg, min, max, count, count_distinct. Optionally group by another column.',
+    category: 'utility',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to the CSV/TSV file.' },
+        column: { type: 'string', description: 'Column to aggregate.' },
+        operation: { type: 'string', description: 'Aggregation operation.', enum: ['sum', 'avg', 'min', 'max', 'count', 'count_distinct'] },
+        group_by: { type: 'string', description: 'Optional column to group by.' },
+      },
+      required: ['file_path', 'column', 'operation'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var column = readStringParam(params, 'column', { required: true });
+      var operation = readStringParam(params, 'operation', { required: true });
+      var groupBy = readStringParam(params, 'group_by');
+
+      try {
+        var data = await readSpreadsheet(filePath, options?.workspaceDir);
+        if (data.headers.indexOf(column) === -1) {
+          return errorResult('Column not found: ' + column + '. Available: ' + data.headers.join(', '));
+        }
+        if (groupBy && data.headers.indexOf(groupBy) === -1) {
+          return errorResult('Group-by column not found: ' + groupBy + '. Available: ' + data.headers.join(', '));
+        }
+
+        function aggregate(rows: Record<string, string>[], col: string, op: string): number | string {
+          var values = rows.map(function(r) { return r[col] ?? ''; });
+          var numericValues = values.map(parseFloat).filter(function(n) { return !isNaN(n); });
+
+          switch (op) {
+            case 'sum': return numericValues.reduce(function(a, b) { return a + b; }, 0);
+            case 'avg': return numericValues.length > 0
+              ? Math.round((numericValues.reduce(function(a, b) { return a + b; }, 0) / numericValues.length) * 10000) / 10000
+              : 0;
+            case 'min': return numericValues.length > 0 ? Math.min.apply(null, numericValues) : 0;
+            case 'max': return numericValues.length > 0 ? Math.max.apply(null, numericValues) : 0;
+            case 'count': return values.length;
+            case 'count_distinct': {
+              var unique = new Set(values);
+              return unique.size;
+            }
+            default: return 0;
+          }
+        }
+
+        if (!groupBy) {
+          var result = aggregate(data.rows, column, operation);
+          return jsonResult({ column: column, operation: operation, result: result, rowCount: data.rows.length });
+        }
+
+        // Group by
+        var groups: Record<string, Record<string, string>[]> = {};
+        for (var row of data.rows) {
+          var key = row[groupBy] ?? '(empty)';
+          if (!groups[key]) groups[key] = [];
+          groups[key].push(row);
+        }
+
+        var groupResults: Array<{ group: string; result: number | string; count: number }> = [];
+        for (var groupKey of Object.keys(groups)) {
+          groupResults.push({
+            group: groupKey,
+            result: aggregate(groups[groupKey], column, operation),
+            count: groups[groupKey].length,
+          });
+        }
+
+        return jsonResult({ column: column, operation: operation, groupBy: groupBy, groups: groupResults });
+      } catch (err: any) {
+        return errorResult('Aggregation failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetTransform: AnyAgentTool = {
+    name: 'ent_sheet_transform',
+    label: 'Transform Spreadsheet',
+    description: 'Transform a CSV/TSV file: sort by column, rename columns, or add a computed column. Returns the transformed data.',
+    category: 'utility',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to the CSV/TSV file.' },
+        action: { type: 'string', description: 'Transform action.', enum: ['sort', 'rename', 'add_column'] },
+        sort_column: { type: 'string', description: 'Column to sort by (for sort action).' },
+        sort_order: { type: 'string', description: 'Sort order: asc or desc (default asc).', enum: ['asc', 'desc'] },
+        rename_from: { type: 'string', description: 'Original column name (for rename action).' },
+        rename_to: { type: 'string', description: 'New column name (for rename action).' },
+        new_column: { type: 'string', description: 'New column name (for add_column action).' },
+        expression: { type: 'string', description: 'Expression for computed column: "concat:col1,col2,separator" or "math:col1+col2" or "upper:col" or "lower:col".' },
+        output_path: { type: 'string', description: 'Optional file path to write the transformed result.' },
+      },
+      required: ['file_path', 'action'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var action = readStringParam(params, 'action', { required: true });
+      var outputPath = readStringParam(params, 'output_path');
+
+      try {
+        var data = await readSpreadsheet(filePath, options?.workspaceDir);
+        var headers = data.headers.slice();
+        var rows = data.rows.map(function(r) { return Object.assign({}, r); });
+
+        switch (action) {
+          case 'sort': {
+            var sortColumn = readStringParam(params, 'sort_column', { required: true });
+            var sortOrder = readStringParam(params, 'sort_order') || 'asc';
+            if (headers.indexOf(sortColumn) === -1) {
+              return errorResult('Sort column not found: ' + sortColumn);
+            }
+            rows.sort(function(a, b) {
+              var va = a[sortColumn] ?? '';
+              var vb = b[sortColumn] ?? '';
+              var na = parseFloat(va);
+              var nb = parseFloat(vb);
+              var cmp: number;
+              if (!isNaN(na) && !isNaN(nb)) {
+                cmp = na - nb;
+              } else {
+                cmp = va.localeCompare(vb);
+              }
+              return sortOrder === 'desc' ? -cmp : cmp;
+            });
+            break;
+          }
+          case 'rename': {
+            var renameFrom = readStringParam(params, 'rename_from', { required: true });
+            var renameTo = readStringParam(params, 'rename_to', { required: true });
+            var idx = headers.indexOf(renameFrom);
+            if (idx === -1) return errorResult('Column not found: ' + renameFrom);
+            headers[idx] = renameTo;
+            for (var row of rows) {
+              row[renameTo] = row[renameFrom];
+              if (renameFrom !== renameTo) delete row[renameFrom];
+            }
+            break;
+          }
+          case 'add_column': {
+            var newColumn = readStringParam(params, 'new_column', { required: true });
+            var expression = readStringParam(params, 'expression', { required: true });
+            headers.push(newColumn);
+
+            for (var row of rows) {
+              if (expression.startsWith('concat:')) {
+                var parts = expression.slice(7).split(',');
+                var sep = parts.length > 2 ? parts[parts.length - 1] : ' ';
+                var cols = parts.length > 2 ? parts.slice(0, -1) : parts;
+                row[newColumn] = cols.map(function(c) { return row[c.trim()] ?? ''; }).join(sep);
+              } else if (expression.startsWith('math:')) {
+                var expr = expression.slice(5);
+                // Simple two-operand math: col1+col2, col1-col2, col1*col2, col1/col2
+                var mathMatch = expr.match(/^(\w+)\s*([+\-*/])\s*(\w+)$/);
+                if (mathMatch) {
+                  var va = parseFloat(row[mathMatch[1]] ?? '0');
+                  var vb = parseFloat(row[mathMatch[3]] ?? '0');
+                  var result: number;
+                  switch (mathMatch[2]) {
+                    case '+': result = va + vb; break;
+                    case '-': result = va - vb; break;
+                    case '*': result = va * vb; break;
+                    case '/': result = vb !== 0 ? va / vb : 0; break;
+                    default: result = 0;
+                  }
+                  row[newColumn] = String(result);
+                } else {
+                  row[newColumn] = '';
+                }
+              } else if (expression.startsWith('upper:')) {
+                var col = expression.slice(6).trim();
+                row[newColumn] = (row[col] ?? '').toUpperCase();
+              } else if (expression.startsWith('lower:')) {
+                var col = expression.slice(6).trim();
+                row[newColumn] = (row[col] ?? '').toLowerCase();
+              } else {
+                row[newColumn] = expression; // literal value
+              }
+            }
+            break;
+          }
+          default:
+            return errorResult('Unknown transform action: ' + action);
+        }
+
+        // Write output if requested
+        if (outputPath) {
+          var outPath = outputPath;
+          if (!path.isAbsolute(outPath) && options?.workspaceDir) {
+            outPath = path.resolve(options.workspaceDir, outPath);
+          }
+          var delimiter = detectDelimiter(outPath);
+          var content = formatCSV(rows, headers, delimiter);
+          var dir = path.dirname(outPath);
+          await fs.mkdir(dir, { recursive: true });
+          await fs.writeFile(outPath, content, 'utf-8');
+          return textResult('Transformed ' + rows.length + ' rows, wrote to ' + outPath);
+        }
+
+        return jsonResult({ headers: headers, rows: rows.slice(0, 100), totalRows: rows.length });
+      } catch (err: any) {
+        return errorResult('Transform failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetMerge: AnyAgentTool = {
+    name: 'ent_sheet_merge',
+    label: 'Merge Spreadsheets',
+    description: 'Join two CSV/TSV files on a shared column. Supports inner, left, right, and full joins.',
+    category: 'utility',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        left_file: { type: 'string', description: 'Path to the left CSV/TSV file.' },
+        right_file: { type: 'string', description: 'Path to the right CSV/TSV file.' },
+        join_column: { type: 'string', description: 'Column name to join on (must exist in both files).' },
+        join_type: { type: 'string', description: 'Join type.', enum: ['inner', 'left', 'right', 'full'] },
+        output_path: { type: 'string', description: 'Optional file path to write the merged result.' },
+      },
+      required: ['left_file', 'right_file', 'join_column'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var leftFile = readStringParam(params, 'left_file', { required: true });
+      var rightFile = readStringParam(params, 'right_file', { required: true });
+      var joinColumn = readStringParam(params, 'join_column', { required: true });
+      var joinType = readStringParam(params, 'join_type') || 'inner';
+      var outputPath = readStringParam(params, 'output_path');
+
+      try {
+        var leftData = await readSpreadsheet(leftFile, options?.workspaceDir);
+        var rightData = await readSpreadsheet(rightFile, options?.workspaceDir);
+
+        if (leftData.headers.indexOf(joinColumn) === -1) {
+          return errorResult('Join column "' + joinColumn + '" not found in left file. Available: ' + leftData.headers.join(', '));
+        }
+        if (rightData.headers.indexOf(joinColumn) === -1) {
+          return errorResult('Join column "' + joinColumn + '" not found in right file. Available: ' + rightData.headers.join(', '));
+        }
+
+        // Build right index
+        var rightIndex: Record<string, Record<string, string>[]> = {};
+        for (var rRow of rightData.rows) {
+          var key = rRow[joinColumn] ?? '';
+          if (!rightIndex[key]) rightIndex[key] = [];
+          rightIndex[key].push(rRow);
+        }
+
+        // Compute merged headers (prefix duplicates with file indicator)
+        var rightOnlyHeaders = rightData.headers.filter(function(h) { return h !== joinColumn; });
+        var mergedHeaders = leftData.headers.slice();
+        for (var rh of rightOnlyHeaders) {
+          if (mergedHeaders.indexOf(rh) >= 0) {
+            mergedHeaders.push(rh + '_right');
+          } else {
+            mergedHeaders.push(rh);
+          }
+        }
+
+        var resultRows: Record<string, string>[] = [];
+        var rightMatched = new Set<string>();
+
+        // Process left rows
+        for (var lRow of leftData.rows) {
+          var lKey = lRow[joinColumn] ?? '';
+          var rightMatches = rightIndex[lKey];
+
+          if (rightMatches && rightMatches.length > 0) {
+            rightMatched.add(lKey);
+            for (var rMatch of rightMatches) {
+              var merged: Record<string, string> = Object.assign({}, lRow);
+              for (var ri = 0; ri < rightOnlyHeaders.length; ri++) {
+                var rHeader = rightOnlyHeaders[ri];
+                var mergedKey = mergedHeaders[leftData.headers.length + ri];
+                merged[mergedKey] = rMatch[rHeader] ?? '';
+              }
+              resultRows.push(merged);
+            }
+          } else if (joinType === 'left' || joinType === 'full') {
+            var merged: Record<string, string> = Object.assign({}, lRow);
+            for (var ri = 0; ri < rightOnlyHeaders.length; ri++) {
+              var mergedKey = mergedHeaders[leftData.headers.length + ri];
+              merged[mergedKey] = '';
+            }
+            resultRows.push(merged);
+          }
+        }
+
+        // Process unmatched right rows for right/full joins
+        if (joinType === 'right' || joinType === 'full') {
+          for (var rRow of rightData.rows) {
+            var rKey = rRow[joinColumn] ?? '';
+            if (!rightMatched.has(rKey)) {
+              var merged: Record<string, string> = {};
+              for (var lh of leftData.headers) {
+                merged[lh] = lh === joinColumn ? rKey : '';
+              }
+              for (var ri = 0; ri < rightOnlyHeaders.length; ri++) {
+                var rHeader = rightOnlyHeaders[ri];
+                var mergedKey = mergedHeaders[leftData.headers.length + ri];
+                merged[mergedKey] = rRow[rHeader] ?? '';
+              }
+              resultRows.push(merged);
+            }
+          }
+        }
+
+        if (outputPath) {
+          var outPath = outputPath;
+          if (!path.isAbsolute(outPath) && options?.workspaceDir) {
+            outPath = path.resolve(options.workspaceDir, outPath);
+          }
+          var delimiter = detectDelimiter(outPath);
+          var content = formatCSV(resultRows, mergedHeaders, delimiter);
+          var dir = path.dirname(outPath);
+          await fs.mkdir(dir, { recursive: true });
+          await fs.writeFile(outPath, content, 'utf-8');
+          return textResult('Merged ' + resultRows.length + ' rows (' + joinType + ' join), wrote to ' + outPath);
+        }
+
+        return jsonResult({
+          headers: mergedHeaders,
+          rows: resultRows.slice(0, 100),
+          totalRows: resultRows.length,
+          joinType: joinType,
+        });
+      } catch (err: any) {
+        return errorResult('Merge failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetPivot: AnyAgentTool = {
+    name: 'ent_sheet_pivot',
+    label: 'Pivot Table',
+    description: 'Create a pivot table from a CSV/TSV file. Group by one column, aggregate values from another column, and optionally spread by a third column.',
+    category: 'utility',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Path to the CSV/TSV file.' },
+        row_column: { type: 'string', description: 'Column to use as row grouping.' },
+        value_column: { type: 'string', description: 'Column to aggregate values from.' },
+        operation: { type: 'string', description: 'Aggregation operation.', enum: ['sum', 'avg', 'count', 'min', 'max'] },
+        spread_column: { type: 'string', description: 'Optional column to spread values across (creates one output column per unique value).' },
+      },
+      required: ['file_path', 'row_column', 'value_column', 'operation'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var filePath = readStringParam(params, 'file_path', { required: true });
+      var rowColumn = readStringParam(params, 'row_column', { required: true });
+      var valueColumn = readStringParam(params, 'value_column', { required: true });
+      var operation = readStringParam(params, 'operation', { required: true });
+      var spreadColumn = readStringParam(params, 'spread_column');
+
+      try {
+        var data = await readSpreadsheet(filePath, options?.workspaceDir);
+        for (var requiredCol of [rowColumn, valueColumn]) {
+          if (data.headers.indexOf(requiredCol) === -1) {
+            return errorResult('Column not found: ' + requiredCol + '. Available: ' + data.headers.join(', '));
+          }
+        }
+        if (spreadColumn && data.headers.indexOf(spreadColumn) === -1) {
+          return errorResult('Spread column not found: ' + spreadColumn);
+        }
+
+        function computeAgg(values: number[], op: string): number {
+          if (values.length === 0) return 0;
+          switch (op) {
+            case 'sum': return values.reduce(function(a, b) { return a + b; }, 0);
+            case 'avg': return Math.round((values.reduce(function(a, b) { return a + b; }, 0) / values.length) * 10000) / 10000;
+            case 'count': return values.length;
+            case 'min': return Math.min.apply(null, values);
+            case 'max': return Math.max.apply(null, values);
+            default: return 0;
+          }
+        }
+
+        if (!spreadColumn) {
+          // Simple pivot: group by row_column, aggregate value_column
+          var groups: Record<string, number[]> = {};
+          for (var row of data.rows) {
+            var groupKey = row[rowColumn] ?? '(empty)';
+            if (!groups[groupKey]) groups[groupKey] = [];
+            var num = parseFloat(row[valueColumn] ?? '');
+            if (!isNaN(num)) groups[groupKey].push(num);
+            else if (operation === 'count') groups[groupKey].push(1);
+          }
+
+          var pivotRows: Record<string, string>[] = [];
+          for (var gk of Object.keys(groups)) {
+            var obj: Record<string, string> = {};
+            obj[rowColumn] = gk;
+            obj[operation + '_' + valueColumn] = String(computeAgg(groups[gk], operation));
+            pivotRows.push(obj);
+          }
+          var pivotHeaders = [rowColumn, operation + '_' + valueColumn];
+          return jsonResult({ headers: pivotHeaders, rows: pivotRows, count: pivotRows.length });
+        }
+
+        // Spread pivot: group by row_column, spread by spread_column
+        var spreadValues = new Set<string>();
+        var matrix: Record<string, Record<string, number[]>> = {};
+
+        for (var row of data.rows) {
+          var rKey = row[rowColumn] ?? '(empty)';
+          var sKey = row[spreadColumn] ?? '(empty)';
+          spreadValues.add(sKey);
+          if (!matrix[rKey]) matrix[rKey] = {};
+          if (!matrix[rKey][sKey]) matrix[rKey][sKey] = [];
+          var num = parseFloat(row[valueColumn] ?? '');
+          if (!isNaN(num)) matrix[rKey][sKey].push(num);
+          else if (operation === 'count') matrix[rKey][sKey].push(1);
+        }
+
+        var spreadCols = Array.from(spreadValues).sort();
+        var pivotHeaders = [rowColumn].concat(spreadCols);
+        var pivotRows: Record<string, string>[] = [];
+
+        for (var rKey of Object.keys(matrix)) {
+          var obj: Record<string, string> = {};
+          obj[rowColumn] = rKey;
+          for (var sc of spreadCols) {
+            obj[sc] = String(computeAgg(matrix[rKey][sc] || [], operation));
+          }
+          pivotRows.push(obj);
+        }
+
+        return jsonResult({ headers: pivotHeaders, rows: pivotRows, count: pivotRows.length });
+      } catch (err: any) {
+        return errorResult('Pivot failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  var entSheetConvert: AnyAgentTool = {
+    name: 'ent_sheet_convert',
+    label: 'Convert Spreadsheet Format',
+    description: 'Convert between tabular data formats: CSV, TSV, JSON, and NDJSON (newline-delimited JSON).',
+    category: 'utility',
+    risk: 'medium',
+    parameters: {
+      type: 'object',
+      properties: {
+        input_path: { type: 'string', description: 'Path to the input file.' },
+        output_path: { type: 'string', description: 'Path to write the output file.' },
+        input_format: { type: 'string', description: 'Input format.', enum: ['csv', 'tsv', 'json', 'ndjson'] },
+        output_format: { type: 'string', description: 'Output format.', enum: ['csv', 'tsv', 'json', 'ndjson'] },
+      },
+      required: ['input_path', 'output_path', 'output_format'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var inputPath = readStringParam(params, 'input_path', { required: true });
+      var outputPath = readStringParam(params, 'output_path', { required: true });
+      var inputFormat = readStringParam(params, 'input_format');
+      var outputFormat = readStringParam(params, 'output_format', { required: true });
+
+      if (!path.isAbsolute(inputPath) && options?.workspaceDir) {
+        inputPath = path.resolve(options.workspaceDir, inputPath);
+      }
+      if (!path.isAbsolute(outputPath) && options?.workspaceDir) {
+        outputPath = path.resolve(options.workspaceDir, outputPath);
+      }
+
+      try {
+        var content = await fs.readFile(inputPath, 'utf-8');
+        var headers: string[];
+        var rows: Record<string, string>[];
+
+        // Detect input format
+        var format = inputFormat;
+        if (!format) {
+          var ext = path.extname(inputPath).toLowerCase();
+          if (ext === '.tsv' || ext === '.tab') format = 'tsv';
+          else if (ext === '.json') format = 'json';
+          else if (ext === '.ndjson' || ext === '.jsonl') format = 'ndjson';
+          else format = 'csv';
+        }
+
+        // Parse input
+        if (format === 'csv') {
+          var parsed = parseCSV(content, ',');
+          headers = parsed.headers;
+          rows = parsed.rows;
+        } else if (format === 'tsv') {
+          var parsed = parseCSV(content, '\t');
+          headers = parsed.headers;
+          rows = parsed.rows;
+        } else if (format === 'json') {
+          var jsonData = JSON.parse(content);
+          if (!Array.isArray(jsonData)) {
+            return errorResult('JSON input must be an array of objects.');
+          }
+          headers = jsonData.length > 0 ? Object.keys(jsonData[0]) : [];
+          rows = jsonData.map(function(item: any) {
+            var row: Record<string, string> = {};
+            for (var h of headers) {
+              row[h] = item[h] != null ? String(item[h]) : '';
+            }
+            return row;
+          });
+        } else if (format === 'ndjson') {
+          var lines = content.split(/\r?\n/).filter(function(l) { return l.trim() !== ''; });
+          var jsonRows = lines.map(function(l) { return JSON.parse(l); });
+          headers = jsonRows.length > 0 ? Object.keys(jsonRows[0]) : [];
+          rows = jsonRows.map(function(item: any) {
+            var row: Record<string, string> = {};
+            for (var h of headers) {
+              row[h] = item[h] != null ? String(item[h]) : '';
+            }
+            return row;
+          });
+        } else {
+          return errorResult('Unsupported input format: ' + format);
+        }
+
+        // Format output
+        var output: string;
+        if (outputFormat === 'csv') {
+          output = formatCSV(rows, headers, ',');
+        } else if (outputFormat === 'tsv') {
+          output = formatCSV(rows, headers, '\t');
+        } else if (outputFormat === 'json') {
+          var jsonOutput = rows.map(function(row) {
+            var obj: Record<string, string> = {};
+            for (var h of headers) { obj[h] = row[h] ?? ''; }
+            return obj;
+          });
+          output = JSON.stringify(jsonOutput, null, 2) + '\n';
+        } else if (outputFormat === 'ndjson') {
+          output = rows.map(function(row) {
+            var obj: Record<string, string> = {};
+            for (var h of headers) { obj[h] = row[h] ?? ''; }
+            return JSON.stringify(obj);
+          }).join('\n') + '\n';
+        } else {
+          return errorResult('Unsupported output format: ' + outputFormat);
+        }
+
+        var dir = path.dirname(outputPath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(outputPath, output, 'utf-8');
+        return textResult('Converted ' + rows.length + ' rows from ' + format + ' to ' + outputFormat + '. Wrote to ' + outputPath);
+      } catch (err: any) {
+        return errorResult('Conversion failed: ' + (err.message || String(err)));
+      }
+    },
+  };
+
+  return [entSheetRead, entSheetWrite, entSheetFilter, entSheetAggregate, entSheetTransform, entSheetMerge, entSheetPivot, entSheetConvert];
+}