@yeyuan98/opencode-bioresearcher-plugin 1.6.8-alpha.2 → 1.7.0

package/dist/tools/table/tools.js

@@ -1,25 +1,32 @@
 import { tool } from '@opencode-ai/plugin/tool';
+import * as fs from 'fs';
 import * as XLSX from 'xlsx';
-import { z } from 'zod';
-import { processCellValue, formatError, resolvePath, getSheet } from './utils';
+import * as z from 'zod';
+import { processCellValue, formatError, resolvePath, getSheet, checkFileSize, writeAtomic, iterativeMin, iterativeMax, DEFAULT_MAX_ROW_CAP, DEFAULT_MAX_RANGE_CELLS, } from './utils';
+const CELL_ADDRESS_REGEX = /^[A-Za-z]+\d+$/;
+const FORCE_DESC = "Override file size / row count limits. Use when you need to work with large files and accept the performance implications.";
 export const tableGetSheetPreview = tool({
     description: "Get first 6 rows of a worksheet to preview data structure",
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
-        sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)")
+        sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableGetSheetPreview", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
-            const data = XLSX.utils.sheet_to_json(worksheet, { header: 1 });
+            const data = XLSX.utils.sheet_to_json(worksheet, { header: 1, range: 6 });
             const previewRows = data.slice(0, 6);
+            const ref = worksheet['!ref'] ? XLSX.utils.decode_range(worksheet['!ref']) : null;
+            const totalRows = ref ? ref.e.r - ref.s.r + 1 : data.length;
             return JSON.stringify({
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
-                total_rows: data.length,
-                preview: previewRows
+                total_rows: totalRows,
+                preview: previewRows,
             }, null, 2);
         }
         catch (error) {
@@ -30,12 +37,14 @@ export const tableGetSheetPreview = tool({
 export const tableListSheets = tool({
     description: "List all worksheet names in a table file",
     args: {
-        file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)")
+        file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableListSheets", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             return JSON.stringify({ sheets: workbook.SheetNames }, null, 2);
         }
@@ -48,20 +57,27 @@ export const tableGetHeaders = tool({
     description: "Get column headers (first row) from a worksheet",
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
-        sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)")
+        sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableGetHeaders", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
-            const data = XLSX.utils.sheet_to_json(worksheet, { header: 1 });
-            const headers = data[0] || [];
+            const ref = worksheet['!ref'] ? XLSX.utils.decode_range(worksheet['!ref']) : { s: { r: 0, c: 0 }, e: { r: 0, c: 0 } };
+            const headers = [];
+            for (let C = ref.s.c; C <= ref.e.c; C++) {
+                const addr = XLSX.utils.encode_cell({ r: ref.s.r, c: C });
+                const cell = worksheet[addr];
+                headers.push(processCellValue(cell));
+            }
             return JSON.stringify({
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 headers: headers,
-                column_count: headers.length
+                column_count: headers.length,
             }, null, 2);
         }
         catch (error) {
@@ -74,12 +90,17 @@ export const tableGetCell = tool({
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
-        cell_address: z.string().describe("Cell address (e.g., 'A1', 'B5')")
+        cell_address: z.string().describe("Cell address (e.g., 'A1', 'B5')"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableGetCell", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
+            if (!CELL_ADDRESS_REGEX.test(args.cell_address)) {
+                throw new Error(`Invalid cell address "${args.cell_address}". Expected format like "A1", "B5", "AA123".`);
+            }
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const cell = worksheet[args.cell_address];
@@ -88,7 +109,7 @@ export const tableGetCell = tool({
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 cell_address: args.cell_address,
                 value: value,
-                type: cell?.t || 'unknown'
+                type: cell?.t || 'unknown',
             }, null, 2);
         }
         catch (error) {
@@ -97,49 +118,90 @@ export const tableGetCell = tool({
     }
 });
 export const tableFilterRows = tool({
-    description: "Filter rows based on a condition (e.g., {column: 'Age', operator: '>', value: 25})",
+    description: "Filter rows by a column value using an operator. Preferred over tableSearch when targeting a specific column. Supports: exact match (=), comparison (>, <, >=, <=), and text matching (contains, starts_with, ends_with). Returns full matching rows. All text matching is case-insensitive.",
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
         column: z.string().describe("Column name to filter on"),
-        operator: z.enum(['=', '!=', '>', '<', '>=', '<=', 'contains']).describe("Comparison operator"),
-        value: z.any().describe("Value to compare against"),
-        max_results: z.number().default(100).describe("Maximum number of results to return")
+        operator: z.enum(['=', '!=', '>', '<', '>=', '<=', 'contains', 'starts_with', 'ends_with']).describe("Comparison operator"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value to compare against"),
+        max_results: z.number().default(100).describe("Maximum number of results to return"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableFilterRows", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
+            const effectiveMax = args.force ? args.max_results : Math.min(args.max_results, DEFAULT_MAX_ROW_CAP);
+            const filteredRows = [];
+            let totalMatchesFound = 0;
             const data = XLSX.utils.sheet_to_json(worksheet);
-            const filteredRows = data.filter(row => {
+            for (let i = 0; i < data.length; i++) {
+                const row = data[i];
                 let cellValue = row[args.column];
                 let comparisonValue = args.value;
-                // Type coercion for numeric comparisons
                 if (typeof cellValue === 'string' && cellValue.trim() !== '' && !isNaN(Number(cellValue))) {
                     cellValue = Number(cellValue);
                 }
                 if (typeof comparisonValue === 'string' && comparisonValue.trim() !== '' && !isNaN(Number(comparisonValue))) {
                     comparisonValue = Number(comparisonValue);
                 }
+                let matches = false;
                 switch (args.operator) {
-                    case '=': return cellValue === comparisonValue;
-                    case '!=': return cellValue !== comparisonValue;
-                    case '>': return cellValue > comparisonValue;
-                    case '<': return cellValue < comparisonValue;
-                    case '>=': return cellValue >= comparisonValue;
-                    case '<=': return cellValue <= comparisonValue;
-                    case 'contains': return String(cellValue).includes(String(comparisonValue));
-                    default: return false;
+                    case '=':
+                        matches = cellValue === comparisonValue;
+                        break;
+                    case '!=':
+                        matches = cellValue !== comparisonValue;
+                        break;
+                    case '>':
+                        matches = cellValue > comparisonValue;
+                        break;
+                    case '<':
+                        matches = cellValue < comparisonValue;
+                        break;
+                    case '>=':
+                        matches = cellValue >= comparisonValue;
+                        break;
+                    case '<=':
+                        matches = cellValue <= comparisonValue;
+                        break;
+                    case 'contains':
+                        matches = String(cellValue).toLowerCase().includes(String(comparisonValue).toLowerCase());
+                        break;
+                    case 'starts_with':
+                        matches = String(cellValue).toLowerCase().startsWith(String(comparisonValue).toLowerCase());
+                        break;
+                    case 'ends_with':
+                        matches = String(cellValue).toLowerCase().endsWith(String(comparisonValue).toLowerCase());
+                        break;
                 }
-            }).slice(0, args.max_results);
-            return JSON.stringify({
+                if (matches) {
+                    totalMatchesFound++;
+                    if (filteredRows.length < effectiveMax) {
+                        filteredRows.push(row);
+                    }
+                }
+                if (!args.force && i >= DEFAULT_MAX_ROW_CAP - 1) {
+                    break;
+                }
+            }
+            const truncated = !args.force && data.length > DEFAULT_MAX_ROW_CAP;
+            const result = {
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 filter: { column: args.column, operator: args.operator, value: args.value },
-                total_matches: filteredRows.length,
-                matched_rows: filteredRows
-            }, null, 2);
+                total_matches_found: totalMatchesFound,
+                returned_count: filteredRows.length,
+                matched_rows: filteredRows,
+            };
+            if (truncated) {
+                result.truncated = true;
+                result.message = `Processed ${DEFAULT_MAX_ROW_CAP} of ${data.length} rows. Set force: true to process all rows.`;
+            }
+            return JSON.stringify(result, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "filter_rows", error });
@@ -147,43 +209,58 @@ export const tableFilterRows = tool({
     }
 });
 export const tableSearch = tool({
-    description: "Search for a term across all cells in a worksheet",
+    description: "Search for a term across all cells in a worksheet using case-insensitive substring matching. Returns individual cell matches (address, value, row index) — not full rows. Use when you don't know which column is relevant. For column-specific filtering, use tableFilterRows.",
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
         search_term: z.string().describe("Term to search for"),
-        max_results: z.number().default(50).describe("Maximum number of results to return")
+        max_results: z.number().default(50).describe("Maximum number of results to return"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableSearch", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const results = [];
             const range = XLSX.utils.decode_range(worksheet['!ref'] || 'A1:A1');
+            const effectiveMax = args.force ? args.max_results : Math.min(args.max_results, DEFAULT_MAX_ROW_CAP);
+            let rowsScanned = 0;
+            let totalMatchesFound = 0;
             for (let R = range.s.r; R <= range.e.r; ++R) {
+                rowsScanned++;
+                if (!args.force && rowsScanned > DEFAULT_MAX_ROW_CAP)
+                    break;
                 for (let C = range.s.c; C <= range.e.c; ++C) {
-                    if (results.length >= args.max_results)
-                        break;
                     const address = XLSX.utils.encode_cell({ r: R, c: C });
                     const cell = worksheet[address];
                     if (cell && cell.v !== undefined) {
                         const cellValue = String(processCellValue(cell)).toLowerCase();
                         if (cellValue.includes(args.search_term.toLowerCase())) {
-                            results.push({ address, value: processCellValue(cell), type: cell.t || 'unknown' });
+                            totalMatchesFound++;
+                            if (results.length < effectiveMax) {
+                                results.push({ address, value: processCellValue(cell), type: cell.t || 'unknown', row_index: R });
+                            }
                         }
                     }
                 }
-                if (results.length >= args.max_results)
-                    break;
             }
-            return JSON.stringify({
+            const truncated = !args.force && rowsScanned >= DEFAULT_MAX_ROW_CAP && range.e.r >= DEFAULT_MAX_ROW_CAP;
+            const result = {
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 search_term: args.search_term,
-                total_found: results.length,
-                results
-            }, null, 2);
+                total_matches_found: totalMatchesFound,
+                returned_count: results.length,
+                rows_scanned: rowsScanned,
+                results,
+            };
+            if (truncated) {
+                result.truncated = true;
+                result.message = `Scanned ${DEFAULT_MAX_ROW_CAP} rows. Set force: true to scan all rows.`;
+            }
+            return JSON.stringify(result, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "search", error });
@@ -195,32 +272,55 @@ export const tableGetRange = tool({
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
-        range: z.string().describe("Cell range (e.g., 'A1:C10', 'A1:B20')")
+        range: z.string().describe("Cell range (e.g., 'A1:C10', 'A1:B20')"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableGetRange", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const range = XLSX.utils.decode_range(args.range);
+            const sheetName = args.sheet_name || workbook.SheetNames[0];
+            const sheetRef = worksheet['!ref'] ? XLSX.utils.decode_range(worksheet['!ref']) : null;
+            if (!sheetRef) {
+                return JSON.stringify({ sheet_name: sheetName, range: args.range, rows: 0, columns: 0, data: [], out_of_bounds: true }, null, 2);
+            }
+            const clamped = {
+                s: { r: Math.max(range.s.r, sheetRef.s.r), c: Math.max(range.s.c, sheetRef.s.c) },
+                e: { r: Math.min(range.e.r, sheetRef.e.r), c: Math.min(range.e.c, sheetRef.e.c) },
+            };
+            if (clamped.s.r > clamped.e.r || clamped.s.c > clamped.e.c) {
+                return JSON.stringify({ sheet_name: sheetName, range: args.range, rows: 0, columns: 0, data: [], out_of_bounds: true }, null, 2);
+            }
+            const totalCells = (clamped.e.r - clamped.s.r + 1) * (clamped.e.c - clamped.s.c + 1);
+            if (!args.force && totalCells > DEFAULT_MAX_RANGE_CELLS) {
+                throw new Error(`Range "${args.range}" exceeds ${DEFAULT_MAX_RANGE_CELLS} cell limit (${totalCells} cells). ` +
+                    `Set force: true to override.`);
+            }
             const data = [];
-            for (let R = range.s.r; R <= range.e.r; ++R) {
+            for (let R = clamped.s.r; R <= clamped.e.r; ++R) {
                 const row = [];
-                for (let C = range.s.c; C <= range.e.c; ++C) {
+                for (let C = clamped.s.c; C <= clamped.e.c; ++C) {
                     const address = XLSX.utils.encode_cell({ r: R, c: C });
                     const cell = worksheet[address];
                     row.push(processCellValue(cell));
                 }
                 data.push(row);
             }
-            return JSON.stringify({
-                sheet_name: args.sheet_name || workbook.SheetNames[0],
+            const result = {
+                sheet_name: sheetName,
                 range: args.range,
                 rows: data.length,
                 columns: data[0]?.length || 0,
-                data
-            }, null, 2);
+                data,
+            };
+            if (clamped.s.r !== range.s.r || clamped.s.c !== range.s.c || clamped.e.r !== range.e.r || clamped.e.c !== range.e.c) {
+                result.clamped_to = XLSX.utils.encode_range(clamped);
+            }
+            return JSON.stringify(result, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "get_range", error });
@@ -232,34 +332,44 @@ export const tableSummarize = tool({
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
-        columns: z.array(z.string()).optional().describe("Specific columns to summarize (empty = all numeric columns)")
+        columns: z.array(z.string()).optional().describe("Specific columns to summarize (empty = all numeric columns)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableSummarize", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const data = XLSX.utils.sheet_to_json(worksheet);
-            const columnsToAnalyze = args.columns && args.columns.length > 0 ? args.columns : Object.keys(data[0] || {});
+            const effectiveData = args.force ? data : data.slice(0, DEFAULT_MAX_ROW_CAP);
+            const columnsToAnalyze = args.columns && args.columns.length > 0 ? args.columns : Object.keys(effectiveData[0] || {});
             const summaries = {};
             columnsToAnalyze.forEach(col => {
-                const values = data.map(row => row[col]).filter(v => typeof v === 'number' && !isNaN(v));
+                const values = effectiveData.map(row => row[col]).filter((v) => typeof v === 'number' && !isNaN(v));
                 if (values.length > 0) {
                     const sum = values.reduce((a, b) => a + b, 0);
                     const avg = sum / values.length;
-                    const min = Math.min(...values);
-                    const max = Math.max(...values);
+                    const min = iterativeMin(values);
+                    const max = iterativeMax(values);
                     const variance = values.reduce((acc, val) => acc + Math.pow(val - avg, 2), 0) / values.length;
                     const stdDev = Math.sqrt(variance);
                     summaries[col] = { sum, avg, min, max, std_dev: stdDev };
                 }
             });
-            return JSON.stringify({
+            const truncated = !args.force && data.length > DEFAULT_MAX_ROW_CAP;
+            const result = {
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
-                row_count: data.length,
-                summaries
-            }, null, 2);
+                row_count: effectiveData.length,
+                summaries,
+            };
+            if (truncated) {
+                result.total_rows = data.length;
+                result.truncated = true;
+                result.message = `Summarized ${DEFAULT_MAX_ROW_CAP} of ${data.length} rows. Set force: true to process all rows.`;
+            }
+            return JSON.stringify(result, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "summarize", error });
@@ -273,17 +383,20 @@ export const tableGroupBy = tool({
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
         group_column: z.string().describe("Column to group by"),
         agg_column: z.string().describe("Column to aggregate"),
-        agg_type: z.enum(['sum', 'count', 'avg', 'min', 'max']).default('sum').describe("Aggregation type")
+        agg_type: z.enum(['sum', 'count', 'avg', 'min', 'max']).default('sum').describe("Aggregation type"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableGroupBy", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const data = XLSX.utils.sheet_to_json(worksheet);
+            const effectiveData = args.force ? data : data.slice(0, DEFAULT_MAX_ROW_CAP);
             const grouped = {};
-            data.forEach(row => {
+            effectiveData.forEach(row => {
                 const groupKey = String(row[args.group_column] || '');
                 const aggValue = row[args.agg_column];
                 if (!grouped[groupKey])
@@ -298,6 +411,10 @@ export const tableGroupBy = tool({
             const result = {};
             Object.keys(grouped).forEach(groupKey => {
                 const values = grouped[groupKey];
+                if (values.length === 0) {
+                    result[groupKey] = 0;
+                    return;
+                }
                 switch (args.agg_type) {
                     case 'sum':
                         result[groupKey] = values.reduce((a, b) => a + b, 0);
@@ -308,21 +425,33 @@ export const tableGroupBy = tool({
                     case 'avg':
                         result[groupKey] = values.reduce((a, b) => a + b, 0) / values.length;
                         break;
-                    case 'min':
-                        result[groupKey] = Math.min(...values);
+                    case 'min': {
+                        const m = iterativeMin(values);
+                        result[groupKey] = m !== undefined ? m : 0;
                         break;
-                    case 'max':
-                        result[groupKey] = Math.max(...values);
+                    }
+                    case 'max': {
+                        const m = iterativeMax(values);
+                        result[groupKey] = m !== undefined ? m : 0;
                         break;
+                    }
                 }
             });
-            return JSON.stringify({
+            const truncated = !args.force && data.length > DEFAULT_MAX_ROW_CAP;
+            const response = {
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 group_column: args.group_column,
                 agg_column: args.agg_column,
                 agg_type: args.agg_type,
-                groups: result
-            }, null, 2);
+                groups: result,
+            };
+            if (truncated) {
+                response.total_rows = data.length;
+                response.processed_rows = effectiveData.length;
+                response.truncated = true;
+                response.message = `Processed ${DEFAULT_MAX_ROW_CAP} of ${data.length} rows. Set force: true to process all rows.`;
+            }
+            return JSON.stringify(response, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "group_by", error });
@@ -337,33 +466,46 @@ export const tablePivotSummary = tool({
         row_field: z.string().describe("Field for row grouping"),
         col_field: z.string().describe("Field for column grouping"),
         value_field: z.string().describe("Field to aggregate"),
-        agg: z.enum(['sum', 'count', 'avg', 'min', 'max']).default('sum').describe("Aggregation type")
+        agg: z.enum(['sum', 'count', 'avg', 'min', 'max']).default('sum').describe("Aggregation type"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tablePivotSummary", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             const data = XLSX.utils.sheet_to_json(worksheet);
+            const effectiveData = args.force ? data : data.slice(0, DEFAULT_MAX_ROW_CAP);
             const pivot = {};
+            const counts = {};
             const allCols = new Set();
-            data.forEach(row => {
+            effectiveData.forEach(row => {
                 const rowKey = String(row[args.row_field] || '');
                 const colKey = String(row[args.col_field] || '');
                 allCols.add(colKey);
                 if (!pivot[rowKey])
                     pivot[rowKey] = {};
+                if (!counts[rowKey])
+                    counts[rowKey] = {};
                 const value = row[args.value_field];
-                if (typeof value === 'number' && !isNaN(value)) {
+                const isNumeric = typeof value === 'number' && !isNaN(value);
+                if (isNumeric) {
                     if (!pivot[rowKey][colKey]) {
                         if (args.agg === 'min') {
                             pivot[rowKey][colKey] = Infinity;
                         }
+                        else if (args.agg === 'max') {
+                            pivot[rowKey][colKey] = -Infinity;
+                        }
                         else {
                             pivot[rowKey][colKey] = 0;
                         }
                     }
+                    if (!counts[rowKey][colKey])
+                        counts[rowKey][colKey] = 0;
+                    counts[rowKey][colKey]++;
                     switch (args.agg) {
                         case 'sum':
                         case 'avg':
@@ -382,31 +524,32 @@ export const tablePivotSummary = tool({
                 }
             });
             if (args.agg === 'avg') {
-                const counts = {};
-                data.forEach(row => {
-                    const rowKey = String(row[args.row_field] || '');
-                    const colKey = String(row[args.col_field] || '');
-                    if (!counts[rowKey])
-                        counts[rowKey] = {};
-                    if (!counts[rowKey][colKey])
-                        counts[rowKey][colKey] = 0;
-                    counts[rowKey][colKey]++;
-                });
                 Object.keys(pivot).forEach(rowKey => {
                     Object.keys(pivot[rowKey]).forEach(colKey => {
-                        pivot[rowKey][colKey] /= counts[rowKey][colKey];
+                        const count = counts[rowKey][colKey];
+                        if (count > 0) {
+                            pivot[rowKey][colKey] /= count;
+                        }
                     });
                 });
             }
-            return JSON.stringify({
+            const truncated = !args.force && data.length > DEFAULT_MAX_ROW_CAP;
+            const response = {
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 row_field: args.row_field,
                 col_field: args.col_field,
                 value_field: args.value_field,
                 agg_type: args.agg,
                 columns: Array.from(allCols).sort(),
-                pivot
-            }, null, 2);
+                pivot,
+            };
+            if (truncated) {
+                response.total_rows = data.length;
+                response.processed_rows = effectiveData.length;
+                response.truncated = true;
+                response.message = `Processed ${DEFAULT_MAX_ROW_CAP} of ${data.length} rows. Set force: true to process all rows.`;
+            }
+            return JSON.stringify(response, null, 2);
         }
         catch (error) {
             return formatError({ file_path: args.file_path, sheet_name: args.sheet_name, operation: "pivot_summary", error });
@@ -418,35 +561,34 @@ export const tableAppendRows = tool({
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
-        rows: z.array(z.union([z.array(z.any()), z.record(z.string(), z.any())])).describe("Rows to append (array of arrays or array of objects)")
+        rows: z.array(z.union([z.array(z.any()), z.record(z.string(), z.any())])).describe("Rows to append (array of arrays or array of objects)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableAppendRows", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
             if (args.rows.length > 0 && Array.isArray(args.rows[0])) {
                 XLSX.utils.sheet_add_aoa(worksheet, args.rows, { origin: -1 });
             }
             else {
-                // Check if sheet already has data (to avoid duplicate headers for object format)
-                const existingData = XLSX.utils.sheet_to_json(worksheet);
-                const hasExistingData = existingData.length > 0;
-                // Only add header if sheet is empty
+                const hasExistingData = !!worksheet['!ref'];
                 const header = hasExistingData ? undefined : Object.keys(args.rows[0] || {});
                 XLSX.utils.sheet_add_json(worksheet, args.rows, {
                     origin: -1,
-                    header
+                    header,
                 });
             }
-            XLSX.writeFile(workbook, resolvedPath);
+            writeAtomic(workbook, resolvedPath);
             return JSON.stringify({
                 success: true,
                 file_path: args.file_path,
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 rows_appended: args.rows.length,
-                message: `Successfully appended ${args.rows.length} rows`
+                message: `Successfully appended ${args.rows.length} rows`,
             }, null, 2);
         }
         catch (error) {
@@ -455,49 +597,55 @@ export const tableAppendRows = tool({
     }
 });
 export const tableUpdateCell = tool({
-    description: "Update a single cell value in a table file",
+    description: "Update a single cell value in a table file. Set value to null to clear a cell.",
     args: {
         file_path: z.string().describe("Path to table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().optional().describe("Worksheet name (optional, uses first sheet by default)"),
         cell_address: z.string().describe("Cell address (e.g., 'A1', 'B5')"),
-        value: z.any().describe("Value to set")
+        value: z.union([z.string(), z.number(), z.boolean(), z.null()]).describe("Value to set (null clears the cell)"),
+        force: z.boolean().default(false).describe(FORCE_DESC),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableUpdateCell", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
+            if (!CELL_ADDRESS_REGEX.test(args.cell_address)) {
+                throw new Error(`Invalid cell address "${args.cell_address}". Expected format like "A1", "B5", "AA123".`);
+            }
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            checkFileSize(resolvedPath, args.force);
             const workbook = XLSX.readFile(resolvedPath);
             const worksheet = getSheet(workbook, args.sheet_name);
-            let cellType;
-            if (typeof args.value === 'number')
-                cellType = 'n';
-            else if (typeof args.value === 'boolean')
-                cellType = 'b';
-            else
-                cellType = 's';
-            worksheet[args.cell_address] = { v: args.value, t: cellType };
+            if (args.value === null) {
+                delete worksheet[args.cell_address];
+            }
+            else {
+                let cellType;
+                if (typeof args.value === 'number')
+                    cellType = 'n';
+                else if (typeof args.value === 'boolean')
+                    cellType = 'b';
+                else
+                    cellType = 's';
+                worksheet[args.cell_address] = { v: args.value, t: cellType };
+            }
             const newCellAddr = XLSX.utils.decode_cell(args.cell_address);
             const currentRef = worksheet['!ref'];
             if (currentRef) {
                 const currentRange = XLSX.utils.decode_range(currentRef);
-                // Only expand range if new cell is significantly beyond current data
-                // Avoid creating sparse sheets by checking if expansion is reasonable
                 const rowDifference = newCellAddr.r - currentRange.e.r;
                 const colDifference = newCellAddr.c - currentRange.e.c;
                 if (newCellAddr.r > currentRange.e.r || newCellAddr.c > currentRange.e.c) {
-                    // Limit expansion to avoid creating sparse sheets
-                    // Only expand if the new cell is reasonably close to existing data
                     const maxReasonableRow = Math.max(currentRange.e.r + 1000, newCellAddr.r);
                     const maxReasonableCol = Math.max(currentRange.e.c + 26, newCellAddr.c);
                     const updatedRange = {
                         s: {
                             r: Math.min(currentRange.s.r, newCellAddr.r),
-                            c: Math.min(currentRange.s.c, newCellAddr.c)
+                            c: Math.min(currentRange.s.c, newCellAddr.c),
                         },
                         e: {
                             r: Math.min(Math.max(currentRange.e.r, newCellAddr.r), maxReasonableRow),
-                            c: Math.min(Math.max(currentRange.e.c, newCellAddr.c), maxReasonableCol)
-                        }
+                            c: Math.min(Math.max(currentRange.e.c, newCellAddr.c), maxReasonableCol),
+                        },
                     };
                     worksheet['!ref'] = XLSX.utils.encode_range(updatedRange);
                 }
@@ -505,14 +653,14 @@ export const tableUpdateCell = tool({
             else {
                 worksheet['!ref'] = XLSX.utils.encode_range({ s: newCellAddr, e: newCellAddr });
             }
-            XLSX.writeFile(workbook, resolvedPath);
+            writeAtomic(workbook, resolvedPath);
             return JSON.stringify({
                 success: true,
                 file_path: args.file_path,
                 sheet_name: args.sheet_name || workbook.SheetNames[0],
                 cell_address: args.cell_address,
                 new_value: args.value,
-                message: `Successfully updated cell ${args.cell_address}`
+                message: `Successfully updated cell ${args.cell_address}`,
             }, null, 2);
         }
         catch (error) {
@@ -525,18 +673,22 @@ export const tableCreateFile = tool({
     args: {
         file_path: z.string().describe("Path for new table file (supports .xlsx, .ods, .csv formats)"),
         sheet_name: z.string().default("Sheet1").describe("Worksheet name"),
-        data: z.any().describe("Data to write (array of arrays or array of objects)")
+        data: z.union([z.array(z.record(z.string(), z.any())), z.array(z.array(z.any())), z.string()]).describe("Data to write (array of arrays, array of objects, or JSON string)"),
+        overwrite: z.boolean().default(false).describe("Overwrite existing file. Set to true if the file already exists."),
     },
     execute: async (args, context) => {
         await context.ask({ permission: "tableCreateFile", patterns: [args.file_path], always: ["*"], metadata: {} });
         try {
             const resolvedPath = resolvePath(args.file_path, context.directory);
+            if (fs.existsSync(resolvedPath) && !args.overwrite) {
+                throw new Error(`File already exists. Set overwrite: true to replace it.`);
+            }
             const workbook = XLSX.utils.book_new();
             let worksheet;
             let parsedData = args.data;
-            if (typeof args.data === 'string') {
+            if (typeof parsedData === 'string') {
                 try {
-                    parsedData = JSON.parse(args.data);
+                    parsedData = JSON.parse(parsedData);
                 }
                 catch (e) {
                     throw new Error(`Failed to parse data string as JSON: ${e}`);
@@ -555,13 +707,13 @@ export const tableCreateFile = tool({
                 worksheet = XLSX.utils.json_to_sheet(parsedData);
             }
             XLSX.utils.book_append_sheet(workbook, worksheet, args.sheet_name);
-            XLSX.writeFile(workbook, resolvedPath);
+            writeAtomic(workbook, resolvedPath);
             return JSON.stringify({
                 success: true,
                 file_path: args.file_path,
                 sheet_name: args.sheet_name,
                 rows_created: parsedData.length,
-                message: `Successfully created Excel file with ${parsedData.length} rows`
+                message: `Successfully created Excel file with ${parsedData.length} rows`,
             }, null, 2);
         }
         catch (error) {