@cicctencent/agent-server 0.2.57 → 0.2.59

package/dist/cjs/sandbox/sandbox-prelude.js

@@ -0,0 +1,645 @@
+"use strict";
+/**
+ * @file Sandbox Prelude - 沙箱基础能力库
+ * @description 注入到每个沙箱 _scripts/_prelude.cjs 的通用工具模块
+ *              通过 runScript preamble 自动暴露为 global.sb
+ *              让 LLM 只需编写业务逻辑，无需重复实现常用功能
+ *
+ * 可用能力:
+ *   - HTTP: sb.fetch / sb.get / sb.post / sb.put / sb.head / sb.del
+ *   - File I/O: sb.readJson / sb.writeJson / sb.readText / sb.writeText / sb.appendText / sb.readCsv / sb.writeCsv / sb.exists / sb.listDir
+ *   - Data: sb.stats / sb.sum / sb.avg / sb.groupBy / sb.sortBy / sb.unique / sb.chunk / sb.range / sb.pick / sb.omit / sb.flatten
+ *   - Date: sb.formatDate / sb.parseDate / sb.now / sb.daysAgo / sb.daysLater / sb.dateDiff
+ *   - String: sb.template / sb.slugify / sb.truncate / sb.pad
+ *   - Table: sb.markdownTable / sb.htmlTable
+ *   - Logger: sb.log.info / sb.log.warn / sb.log.error / sb.log.debug
+ *
+ * == 扩展机制 ==
+ * 基础能力可通过「扩展」机制注册，无需修改本文件：
+ *   1. 全局注册（作用于所有沙箱）：
+ *        import { registerSandboxPreludeExtension } from '@cicctencent/agent-server';
+ *        registerSandboxPreludeExtension('myUtil', `
+ *          module.exports = {
+ *            greet(name) { return 'Hello, ' + name; },
+ *          };
+ *        `);
+ *   2. 会话级注册（仅作用于单个沙箱）：
+ *        sandboxManager.create(sessionId, { preludeExtensions: { myUtil: 'module.exports = { ... };' } });
+ * 扩展模块需通过 module.exports 导出对象，prelude 会在加载时将其合并进 global.sb
+ * （同名 key 会覆盖核心能力，便于定制）。扩展文件位于 _scripts/_prelude_ext/<name>.cjs。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANDBOX_PRELUDE_SOURCE = void 0;
+exports.registerSandboxPreludeExtension = registerSandboxPreludeExtension;
+exports.getSandboxPreludeExtensions = getSandboxPreludeExtensions;
+exports.clearSandboxPreludeExtensions = clearSandboxPreludeExtensions;
+const SANDBOX_PRELUDE_EXTENSIONS = [];
+/**
+ * 注册一个沙箱基础能力扩展（全局生效，作用于之后创建的所有沙箱）
+ * @param name 扩展名，仅允许 [a-zA-Z0-9_-]
+ * @param source 扩展 CommonJS 源码，需通过 module.exports 导出对象
+ * @example
+ *   registerSandboxPreludeExtension('csv', `module.exports = { parse(text){ return text.split('\\n'); } };`);
+ */
+function registerSandboxPreludeExtension(name, source) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`Invalid prelude extension name "${name}". Only [a-zA-Z0-9_-] allowed.`);
+    }
+    if (typeof source !== 'string' || !source.trim()) {
+        throw new Error(`Prelude extension "${name}" source must be a non-empty string.`);
+    }
+    const idx = SANDBOX_PRELUDE_EXTENSIONS.findIndex((e) => e.name === name);
+    if (idx >= 0) {
+        SANDBOX_PRELUDE_EXTENSIONS[idx] = { name, source };
+    }
+    else {
+        SANDBOX_PRELUDE_EXTENSIONS.push({ name, source });
+    }
+}
+/** 获取当前注册的所有扩展 */
+function getSandboxPreludeExtensions() {
+    return SANDBOX_PRELUDE_EXTENSIONS.map((e) => ({ ...e }));
+}
+/** 清空所有已注册的扩展（主要用于测试） */
+function clearSandboxPreludeExtensions() {
+    SANDBOX_PRELUDE_EXTENSIONS.length = 0;
+}
+/**
+ * _prelude.cjs 源代码
+ * 在沙箱初始化时写入 _scripts/_prelude.cjs
+ * 通过 runScript Node.js preamble 自动 require 为 global.sb
+ */
+exports.SANDBOX_PRELUDE_SOURCE = `'use strict';
+// ============================================================
+// Sandbox Prelude - Auto-loaded as global \`sb\` in Node.js scripts
+// Common utilities so you only write business logic.
+// Loads extensions from _prelude_ext/ at require time.
+// ============================================================
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+// ===== Helpers =====
+
+// Safe JSON stringify (handles circular references)
+function _safeStringify(v) {
+  try { return JSON.stringify(v); } catch (e) { return String(v); }
+}
+
+// ===== HTTP =====
+
+/**
+ * fetch - HTTP request with timeout, JSON parsing and redirect following
+ * @param {string} url - Request URL
+ * @param {object} options - { method, headers, body, json, params, timeout, maxRedirects }
+ * @returns {Promise<{status, headers, data, text}>}
+ */
+async function fetch(url, options = {}, _depth = 0) {
+  const {
+    method = 'GET',
+    headers = {},
+    body,
+    json,
+    timeout = 30000,
+    params,
+    maxRedirects = 3,
+  } = options;
+  let targetUrl = url;
+  if (params) {
+    const u = new URL(targetUrl);
+    for (const [k, v] of Object.entries(params)) u.searchParams.set(k, String(v));
+    targetUrl = u.toString();
+  }
+  const u = new URL(targetUrl);
+  const lib = u.protocol === 'https:' ? https : http;
+  const reqHeaders = { 'User-Agent': 'workai-sandbox/1.0', ...headers };
+  let reqBody = body;
+  if (json !== undefined) {
+    reqBody = JSON.stringify(json);
+    reqHeaders['Content-Type'] = reqHeaders['Content-Type'] || 'application/json';
+  }
+  return new Promise((resolve, reject) => {
+    const req = lib.request(u, { method, headers: reqHeaders, timeout }, (res) => {
+      const status = res.statusCode;
+      // Follow redirects (301/302/303/307/308)
+      if (
+        (status === 301 || status === 302 || status === 303 || status === 307 || status === 308) &&
+        res.headers.location &&
+        _depth < maxRedirects
+      ) {
+        res.resume(); // discard response body
+        const nextUrl = new URL(res.headers.location, targetUrl).toString();
+        const nextMethod = status === 303 ? 'GET' : method;
+        const nextBody = status === 303 ? undefined : body;
+        const nextJson = status === 303 ? undefined : json;
+        resolve(fetch(nextUrl, { ...options, method: nextMethod, body: nextBody, json: nextJson }, _depth + 1));
+        return;
+      }
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const buf = Buffer.concat(chunks);
+        const text = buf.toString('utf-8');
+        let data = text;
+        const ct = (res.headers['content-type'] || '').toLowerCase();
+        if (ct.includes('application/json') || ct.includes('+json')) {
+          try { data = JSON.parse(text); } catch (e) { /* keep text */ }
+        }
+        resolve({ status: status, headers: res.headers, data, text });
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(new Error('Request timeout after ' + timeout + 'ms')); });
+    if (reqBody) req.write(reqBody);
+    req.end();
+  });
+}
+
+/** GET request shorthand */
+async function get(url, options = {}) {
+  return fetch(url, { ...options, method: 'GET' });
+}
+
+/** POST request shorthand (auto-JSON for object bodies) */
+async function post(url, body, options = {}) {
+  const isJson = typeof body === 'object' && body !== null && !Buffer.isBuffer(body);
+  return fetch(url, {
+    ...options,
+    method: 'POST',
+    json: isJson ? body : undefined,
+    body: isJson ? undefined : body,
+  });
+}
+
+/** PUT request shorthand (auto-JSON for object bodies) */
+async function put(url, body, options = {}) {
+  const isJson = typeof body === 'object' && body !== null && !Buffer.isBuffer(body);
+  return fetch(url, {
+    ...options,
+    method: 'PUT',
+    json: isJson ? body : undefined,
+    body: isJson ? undefined : body,
+  });
+}
+
+/** HEAD request shorthand */
+async function head(url, options = {}) {
+  return fetch(url, { ...options, method: 'HEAD' });
+}
+
+/** DELETE request shorthand */
+async function del(url, options = {}) {
+  return fetch(url, { ...options, method: 'DELETE' });
+}
+
+// ===== File I/O =====
+
+function readJson(file) {
+  const content = fs.readFileSync(file, 'utf-8');
+  return JSON.parse(content);
+}
+
+function writeJson(file, data, indent = 2) {
+  const dir = path.dirname(file);
+  if (dir && dir !== '.') try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  fs.writeFileSync(file, JSON.stringify(data, null, indent), 'utf-8');
+}
+
+function readText(file, encoding = 'utf-8') {
+  return fs.readFileSync(file, encoding);
+}
+
+function writeText(file, content) {
+  const dir = path.dirname(file);
+  if (dir && dir !== '.') try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  fs.writeFileSync(file, content, 'utf-8');
+}
+
+function appendText(file, content) {
+  const dir = path.dirname(file);
+  if (dir && dir !== '.') try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  fs.appendFileSync(file, content, 'utf-8');
+}
+
+function exists(p) {
+  try { return fs.existsSync(p); } catch (e) { return false; }
+}
+
+function listDir(dir) {
+  return fs.readdirSync(dir).map(function (name) {
+    let stat;
+    try { stat = fs.statSync(path.join(dir, name)); } catch (e) { return name; }
+    return stat.isDirectory() ? name + '/' : name;
+  });
+}
+
+/**
+ * readCsv - parse CSV file into array of objects
+ * @param {string} file - CSV file path
+ * @param {object} opts - { delimiter, headers }
+ *   headers: 自定义表头数组；若提供则首行被视为数据行，否则首行作为表头
+ * @returns {Array<object>}
+ */
+function readCsv(file, opts = {}) {
+  const delimiter = opts.delimiter || ',';
+  const content = fs.readFileSync(file, 'utf-8');
+  const lines = content.split(/\\r?\\n/).filter(function (l) { return l.trim(); });
+  if (lines.length === 0) return [];
+  const parseLine = function (line) {
+    const result = [];
+    let cur = '';
+    let inQuote = false;
+    for (let i = 0; i < line.length; i++) {
+      const c = line[i];
+      if (c === '"') {
+        if (inQuote && line[i + 1] === '"') { cur += '"'; i++; }
+        else inQuote = !inQuote;
+      } else if (c === delimiter && !inQuote) {
+        result.push(cur); cur = '';
+      } else {
+        cur += c;
+      }
+    }
+    result.push(cur);
+    return result.map(function (s) { return s.trim(); });
+  };
+  const headers = opts.headers || parseLine(lines[0]);
+  const startIdx = opts.headers ? 0 : 1;
+  const rows = [];
+  for (let i = startIdx; i < lines.length; i++) {
+    const values = parseLine(lines[i]);
+    const row = {};
+    headers.forEach(function (h, j) { row[h] = values[j] || ''; });
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * writeCsv - write array of objects to CSV file
+ * @param {string} file - Output CSV file path
+ * @param {Array<object>} rows - Data rows
+ * @param {object} opts - { headers, delimiter }
+ */
+function writeCsv(file, rows, opts = {}) {
+  if (!rows || rows.length === 0) {
+    writeText(file, '');
+    return;
+  }
+  const delimiter = opts.delimiter || ',';
+  const headers = opts.headers || Object.keys(rows[0]);
+  const escapeCell = function (val) {
+    const s = String(val == null ? '' : val);
+    if (s.includes(delimiter) || s.includes('"') || s.includes('\\n')) {
+      return '"' + s.replace(/"/g, '""') + '"';
+    }
+    return s;
+  };
+  const lines = [headers.map(escapeCell).join(delimiter)];
+  for (const row of rows) {
+    lines.push(headers.map(function (h) { return escapeCell(row[h]); }).join(delimiter));
+  }
+  writeText(file, lines.join('\\n'));
+}
+
+// ===== Data Utilities =====
+
+/** Calculate statistics: sum, avg, min, max, count, std */
+function stats(arr) {
+  const nums = arr.map(Number).filter(function (n) { return !isNaN(n); });
+  if (nums.length === 0) return { count: 0, sum: 0, avg: 0, min: 0, max: 0, std: 0 };
+  const sumVal = nums.reduce(function (a, b) { return a + b; }, 0);
+  const avgVal = sumVal / nums.length;
+  const min = Math.min.apply(null, nums);
+  const max = Math.max.apply(null, nums);
+  const variance = nums.reduce(function (acc, n) { return acc + Math.pow(n - avgVal, 2); }, 0) / nums.length;
+  return { count: nums.length, sum: sumVal, avg: avgVal, min: min, max: max, std: Math.sqrt(variance) };
+}
+
+function sum(arr) {
+  return arr.reduce(function (a, b) { return a + (Number(b) || 0); }, 0);
+}
+
+function avg(arr) {
+  if (arr.length === 0) return 0;
+  return sum(arr) / arr.length;
+}
+
+function groupBy(arr, keyFn) {
+  const result = {};
+  for (const item of arr) {
+    const key = typeof keyFn === 'function' ? keyFn(item) : item[keyFn];
+    if (!result[key]) result[key] = [];
+    result[key].push(item);
+  }
+  return result;
+}
+
+function sortBy(arr, keyFn, desc) {
+  const fn = typeof keyFn === 'function' ? keyFn : function (x) { return x[keyFn]; };
+  return arr.slice().sort(function (a, b) {
+    const va = fn(a);
+    const vb = fn(b);
+    if (va < vb) return desc ? 1 : -1;
+    if (va > vb) return desc ? -1 : 1;
+    return 0;
+  });
+}
+
+function unique(arr, keyFn) {
+  if (!keyFn) {
+    return arr.filter(function (v, i, self) { return self.indexOf(v) === i; });
+  }
+  const fn = typeof keyFn === 'function' ? keyFn : function (x) { return x[keyFn]; };
+  const seen = new Set();
+  return arr.filter(function (x) {
+    const k = fn(x);
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+function chunk(arr, size) {
+  size = Math.max(1, size || 1);
+  const result = [];
+  for (let i = 0; i < arr.length; i += size) {
+    result.push(arr.slice(i, i + size));
+  }
+  return result;
+}
+
+function range(start, end, step) {
+  step = step || 1;
+  if (end === undefined) { end = start; start = 0; }
+  const result = [];
+  if (step > 0) {
+    for (let i = start; i < end; i += step) result.push(i);
+  } else {
+    for (let i = start; i > end; i += step) result.push(i);
+  }
+  return result;
+}
+
+function pick(obj, keys) {
+  const result = {};
+  for (const k of keys) {
+    if (k in obj) result[k] = obj[k];
+  }
+  return result;
+}
+
+function omit(obj, keys) {
+  const keySet = new Set(keys);
+  const result = {};
+  for (const k of Object.keys(obj)) {
+    if (!keySet.has(k)) result[k] = obj[k];
+  }
+  return result;
+}
+
+function flatten(arr) {
+  return arr.reduce(function (flat, sub) { return flat.concat(Array.isArray(sub) ? sub : [sub]); }, []);
+}
+
+// ===== Date Utilities =====
+
+function formatDate(date, format) {
+  const d = date instanceof Date ? date : new Date(date);
+  if (isNaN(d.getTime())) return 'Invalid Date';
+  const pad = function (n) { return n < 10 ? '0' + n : '' + n; };
+  const map = {
+    YYYY: d.getFullYear(),
+    MM: pad(d.getMonth() + 1),
+    DD: pad(d.getDate()),
+    HH: pad(d.getHours()),
+    mm: pad(d.getMinutes()),
+    ss: pad(d.getSeconds()),
+  };
+  let result = format || 'YYYY-MM-DD HH:mm:ss';
+  for (const k in map) {
+    result = result.replace(k, map[k]);
+  }
+  return result;
+}
+
+function parseDate(str) {
+  if (typeof str === 'number') return new Date(str);
+  const d = new Date(str);
+  if (!isNaN(d.getTime())) return d;
+  const m = String(str).match(/^(\\d{4})[-\\/](\\d{1,2})[-\\/](\\d{1,2})/);
+  if (m) return new Date(parseInt(m[1], 10), parseInt(m[2], 10) - 1, parseInt(m[3], 10));
+  return null;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function daysAgo(n) {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d;
+}
+
+function daysLater(n) {
+  const d = new Date();
+  d.setDate(d.getDate() + n);
+  return d;
+}
+
+function dateDiff(d1, d2, unit) {
+  const date1 = d1 instanceof Date ? d1 : new Date(d1);
+  const date2 = d2 instanceof Date ? d2 : new Date(d2);
+  const diffMs = Math.abs(date2.getTime() - date1.getTime());
+  unit = unit || 'days';
+  switch (unit) {
+    case 'seconds': return Math.floor(diffMs / 1000);
+    case 'minutes': return Math.floor(diffMs / 60000);
+    case 'hours': return Math.floor(diffMs / 3600000);
+    case 'days': return Math.floor(diffMs / 86400000);
+    default: return diffMs;
+  }
+}
+
+// ===== String Utilities =====
+
+/**
+ * template - Simple template interpolation
+ * @param {string} str - Template string with {variable} or {a.b.c} placeholders
+ * @param {object} data - Data object
+ * @returns {string}
+ */
+function template(str, data) {
+  return str.replace(/\\{([^}]+)\\}/g, function (match, key) {
+    const value = key.trim().split('.').reduce(function (obj, k) {
+      return obj && obj[k] !== undefined ? obj[k] : undefined;
+    }, data);
+    return value !== undefined && value !== null ? String(value) : '';
+  });
+}
+
+function slugify(str) {
+  return String(str)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function truncate(str, len, suffix) {
+  if (String(str).length <= len) return String(str);
+  return String(str).substring(0, len) + (suffix || '...');
+}
+
+function pad(str, len, char, right) {
+  str = String(str);
+  char = char || ' ';
+  const diff = len - str.length;
+  if (diff <= 0) return str;
+  const padding = char.repeat(diff);
+  return right ? str + padding : padding + str;
+}
+
+// ===== Table Generators =====
+
+/**
+ * markdownTable - Generate markdown table from array of objects
+ * @param {Array<object>} rows - Data rows
+ * @param {Array<string>} headers - Optional custom headers (defaults to Object.keys of first row)
+ * @returns {string} Markdown table string
+ */
+function markdownTable(rows, headers) {
+  if (!rows || rows.length === 0) return '';
+  headers = headers || Object.keys(rows[0]);
+  const lines = [];
+  lines.push('| ' + headers.join(' | ') + ' |');
+  lines.push('| ' + headers.map(function () { return '---'; }).join(' | ') + ' |');
+  for (const row of rows) {
+    lines.push('| ' + headers.map(function (h) {
+      return String(row[h] == null ? '' : row[h]).replace(/\\|/g, '\\\\|');
+    }).join(' | ') + ' |');
+  }
+  return lines.join('\\n');
+}
+
+/**
+ * htmlTable - Generate HTML table from array of objects
+ * @param {Array<object>} rows - Data rows
+ * @param {object} opts - { headers, tableClass }
+ * @returns {string} HTML table string
+ */
+function htmlTable(rows, opts = {}) {
+  if (!rows || rows.length === 0) return '<table><tbody></tbody></table>';
+  const headers = opts.headers || Object.keys(rows[0]);
+  const tableClass = opts.tableClass ? ' class="' + opts.tableClass + '"' : '';
+  const parts = ['<table' + tableClass + '>'];
+  parts.push('<thead><tr>');
+  for (const h of headers) {
+    parts.push('<th>' + h + '</th>');
+  }
+  parts.push('</tr></thead><tbody>');
+  for (const row of rows) {
+    parts.push('<tr>');
+    for (const h of headers) {
+      parts.push('<td>' + String(row[h] == null ? '' : row[h]) + '</td>');
+    }
+    parts.push('</tr>');
+  }
+  parts.push('</tbody></table>');
+  return parts.join('');
+}
+
+// ===== Logger =====
+
+const log = {
+  info: function (msg, meta) { console.log('[INFO] ' + msg + (meta !== undefined ? ' ' + _safeStringify(meta) : '')); },
+  warn: function (msg, meta) { console.warn('[WARN] ' + msg + (meta !== undefined ? ' ' + _safeStringify(meta) : '')); },
+  error: function (msg, meta) { console.error('[ERROR] ' + msg + (meta !== undefined ? ' ' + _safeStringify(meta) : '')); },
+  debug: function (msg, meta) { console.log('[DEBUG] ' + msg + (meta !== undefined ? ' ' + _safeStringify(meta) : '')); },
+};
+
+// ===== Core exports =====
+
+const _exports = {
+  // HTTP
+  fetch: fetch,
+  get: get,
+  post: post,
+  put: put,
+  head: head,
+  del: del,
+  // File I/O
+  readJson: readJson,
+  writeJson: writeJson,
+  readText: readText,
+  writeText: writeText,
+  appendText: appendText,
+  readCsv: readCsv,
+  writeCsv: writeCsv,
+  exists: exists,
+  listDir: listDir,
+  // Data
+  stats: stats,
+  sum: sum,
+  avg: avg,
+  groupBy: groupBy,
+  sortBy: sortBy,
+  unique: unique,
+  chunk: chunk,
+  range: range,
+  pick: pick,
+  omit: omit,
+  flatten: flatten,
+  // Date
+  formatDate: formatDate,
+  parseDate: parseDate,
+  now: now,
+  daysAgo: daysAgo,
+  daysLater: daysLater,
+  dateDiff: dateDiff,
+  // String
+  template: template,
+  slugify: slugify,
+  truncate: truncate,
+  pad: pad,
+  // Table
+  markdownTable: markdownTable,
+  htmlTable: htmlTable,
+  // Logger
+  log: log,
+  // fs/path passthrough for convenience
+  fs: fs,
+  path: path,
+};
+
+module.exports = _exports;
+
+// ===== Load extensions from _prelude_ext/ =====
+// 扩展模块通过 module.exports 导出对象，加载时合并进 sb（同名覆盖核心，便于定制）
+(function loadPreludeExtensions() {
+  try {
+    const extDir = path.join(__dirname, '_prelude_ext');
+    if (!fs.existsSync(extDir)) return;
+    const extFiles = fs.readdirSync(extDir).filter(function (f) {
+      return f.endsWith('.cjs') && f !== 'index.cjs';
+    });
+    for (const f of extFiles) {
+      try {
+        const mod = require(path.join(extDir, f));
+        const ext = mod && mod.__esModule && mod.default ? mod.default : mod;
+        if (ext && typeof ext === 'object') {
+          for (const key of Object.keys(ext)) {
+            _exports[key] = ext[key];
+          }
+        }
+      } catch (e) {
+        console.warn('[prelude] Failed to load extension "' + f + '": ' + (e && e.message));
+      }
+    }
+  } catch (e) { /* ignore extension load errors */ }
+})();
+`;
+//# sourceMappingURL=sandbox-prelude.js.map

package/dist/cjs/sandbox/sandbox-prelude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-prelude.js","sourceRoot":"","sources":["../../../src/sandbox/sandbox-prelude.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAoBH,0EAaC;AAGD,kEAEC;AAGD,sEAEC;AAhCD,MAAM,0BAA0B,GAA8B,EAAE,CAAC;AAEjE;;;;;;GAMG;AACH,SAAgB,+BAA+B,CAAC,IAAY,EAAE,MAAc;IAC1E,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,gCAAgC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,sCAAsC,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,GAAG,GAAG,0BAA0B,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACzE,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,0BAA0B,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,0BAA0B,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;AACH,CAAC;AAED,kBAAkB;AAClB,SAAgB,2BAA2B;IACzC,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,yBAAyB;AACzB,SAAgB,6BAA6B;IAC3C,0BAA0B,CAAC,MAAM,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACU,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4jBrC,CAAC"}

package/dist/cjs/tool/tools/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../../src/tool/tools/sandbox.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,yBAAyB,CAAC;AAKvE,wBAAgB,kBAAkB,IAAI,cAAc,EAAE,CA+XrD"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../../src/tool/tools/sandbox.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAW,MAAM,yBAAyB,CAAC;AAKvE,wBAAgB,kBAAkB,IAAI,cAAc,EAAE,CA2YrD"}

package/dist/cjs/tool/tools/sandbox.js

@@ -61,7 +61,19 @@ function createSandboxTools() {
                         'Supported languages: nodejs, python, shell. ' +
                         'Node.js scripts use CommonJS (.cjs) — `require()` and `module.exports` are supported. ' +
                         'npm packages are NOT pre-installed; use `execute_command` with the preferred package manager from Runtime env (e.g. `pnpm install`, `yarn add`, or `npm install`) with `timeout: 60000`. ' +
-                        'For PDF generation: prefer Python with `weasyprint` or `reportlab`.',
+                        'For PDF generation: prefer Python with `weasyprint` or `reportlab`.\n\n' +
+                        '**BUILT-IN SANDBOX UTILITIES (global `sb`):**\n' +
+                        'A global `sb` object is auto-loaded in all Node.js sandbox scripts. USE IT instead of writing common utilities from scratch:\n' +
+                        '- **HTTP**: `sb.fetch(url, {method, headers, json, params, timeout})` -> {status, data, text}; `sb.get(url)` / `sb.post(url, body)` shorthands\n' +
+                        '- **File I/O**: `sb.readJson(file)` / `sb.writeJson(file, data)` / `sb.readText(file)` / `sb.writeText(file, str)` / `sb.readCsv(file)` / `sb.writeCsv(file, rows)` / `sb.exists(path)` / `sb.listDir(dir)`\n' +
+                        '- **Data**: `sb.stats(arr)` -> {sum, avg, min, max, std, count}; `sb.sum(arr)` / `sb.avg(arr)` / `sb.groupBy(arr, key)` / `sb.sortBy(arr, key, desc)` / `sb.unique(arr, key)` / `sb.chunk(arr, size)` / `sb.range(start, end)` / `sb.pick(obj, keys)` / `sb.flatten(arr)\n' +
+                        '- **Date**: `sb.formatDate(date, "YYYY-MM-DD")` / `sb.parseDate(str)` / `sb.now()` / `sb.daysAgo(n)` / `sb.daysLater(n)` / `sb.dateDiff(d1, d2, "days")`\n' +
+                        '- **String**: `sb.template("Hello {name}", {name: "World"})` / `sb.slugify(str)` / `sb.truncate(str, len)` / `sb.pad(str, len, char)\n' +
+                        '- **Table**: `sb.markdownTable(rows, headers?)` / `sb.htmlTable(rows, {headers?, tableClass?})\n' +
+                        '- **Logger**: `sb.log.info(msg, meta?)` / `sb.log.warn(msg)` / `sb.log.error(msg)` / `sb.log.debug(msg)\n' +
+                        '- **Passthrough**: `sb.fs` / `sb.path` (Node.js built-in modules)\n' +
+                        'Example: `const data = sb.readJson("input.json"); const grouped = sb.groupBy(data, "category"); const stats = sb.stats(data.map(d => d.value)); sb.log.info("Processed " + data.length + " items");`\n' +
+                        'Also available: `require("./_scripts/_json_builder")` for building large JSON data files, and `require("./_scripts/_html_renderer")` for HTML report generation.',
                     parameters: {
                         type: 'object',
                         properties: {