squidclaw 2.5.0 → 2.7.0

package/lib/builtin-plugins/analytics/index.js

@@ -0,0 +1,23 @@
+let messageCount = 0;
+let startTime = Date.now();
+
+export async function onMessage({ message, contactId, agentId, engine }) {
+  messageCount++;
+  return null; // Don't intercept, just count
+}
+
+export function getTools() {
+  return [
+    '### Analytics Report',
+    '---TOOL:analytics:report---',
+    'Show messaging analytics and stats for this session.',
+  ];
+}
+
+export async function onTool({ toolName, engine }) {
+  if (toolName !== 'analytics') return null;
+  const uptime = ((Date.now() - startTime) / 3600000).toFixed(1);
+  return {
+    result: `📊 Session Analytics:\n• Messages this session: ${messageCount}\n• Session uptime: ${uptime}h\n• Engine uptime: ${(process.uptime() / 3600).toFixed(1)}h\n• Memory: ${(process.memoryUsage().rss / 1024 / 1024).toFixed(0)} MB`,
+  };
+}

package/lib/builtin-plugins/analytics/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "analytics",
+  "version": "1.0.0",
+  "description": "Track message patterns, response times, popular topics",
+  "author": "Squidclaw",
+  "hooks": ["onMessage", "onTool", "getTools"]
+}

package/lib/builtin-plugins/auto-responder/index.js

@@ -0,0 +1,16 @@
+let responses = {};
+
+export async function onLoad({ config }) {
+  responses = config.responses || {
+    'ping': 'pong! 🏓',
+    'marco': 'polo! 🏊',
+  };
+}
+
+export async function onMessage({ message }) {
+  const lower = message.toLowerCase().trim();
+  if (responses[lower]) {
+    return { handled: true, response: responses[lower] };
+  }
+  return null;
+}

package/lib/builtin-plugins/auto-responder/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "auto-responder",
+  "version": "1.0.0",
+  "description": "Auto-respond to common phrases (customizable)",
+  "author": "Squidclaw",
+  "hooks": ["onLoad", "onMessage"]
+}

package/lib/builtin-plugins/translator/index.js

@@ -0,0 +1,22 @@
+export function getTools() {
+  return [
+    '### Translate Text',
+    '---TOOL:translate:target_language|text to translate---',
+    'Translate text to another language. Examples: translate:arabic|Hello world, translate:english|مرحبا',
+  ];
+}
+
+export async function onTool({ toolName, toolArg, engine }) {
+  if (toolName !== 'translate') return null;
+  const pipeIdx = toolArg.indexOf('|');
+  if (pipeIdx === -1) return { result: 'Format: language|text' };
+  const lang = toolArg.slice(0, pipeIdx).trim();
+  const text = toolArg.slice(pipeIdx + 1).trim();
+  
+  const response = await engine.aiGateway.chat([
+    { role: 'system', content: `Translate the following text to ${lang}. Return ONLY the translation, nothing else.` },
+    { role: 'user', content: text },
+  ], { model: engine.config.ai?.defaultModel });
+  
+  return { result: response.content };
+}

package/lib/builtin-plugins/translator/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "translator",
+  "version": "1.0.0",
+  "description": "Auto-detect and translate messages between languages",
+  "author": "Squidclaw",
+  "hooks": ["onTool", "getTools"]
+}

package/lib/channels/telegram/bot.js

@@ -208,7 +208,8 @@ export class TelegramManager {
     const chatId = contactId.replace('tg_', '');
     const { readFileSync } = await import('fs');
     const buffer = readFileSync(filePath);
-    await botInfo.bot.api.sendDocument(chatId, new InputFile(buffer, fileName || 'file'), {
+    const { InputFile: IF } = await import("grammy");
+    await botInfo.bot.api.sendDocument(chatId, new IF(buffer, fileName || 'file'), {
       caption: caption || '',
     });
     logger.info('telegram', 'Sent document: ' + fileName);

package/lib/engine.js

@@ -63,6 +63,8 @@ export class SquidclawEngine {
     pipeline.use('auto-links', autoLinksMiddleware);
     pipeline.use('auto-memory', autoMemoryMiddleware);
     const { configChatMiddleware } = await import('./middleware/config-chat.js');
+    const { pluginMiddleware } = await import('./middleware/plugins.js');
+    pipeline.use('plugins', pluginMiddleware);
     pipeline.use('config-chat', configChatMiddleware);
     pipeline.use('skill-check', skillCheckMiddleware);
     pipeline.use('typing', typingMiddleware);        // wraps AI call with typing indicator
@@ -226,6 +228,27 @@ export class SquidclawEngine {
       if (pending.c > 0) console.log(`  ⏰ Reminders: ${pending.c} pending`);
     } catch {}
 
+    // Sandbox
+    try {
+      const { Sandbox } = await import('./features/sandbox.js');
+      this.sandbox = new Sandbox({
+        timeout: 15000,
+        maxMemory: 64,
+        maxFiles: 100,
+      });
+      // Cleanup old files every hour
+      setInterval(() => this.sandbox.cleanup(), 3600000);
+    } catch (err) { logger.error('engine', 'Sandbox init failed: ' + err.message); }
+
+    // Plugins
+    try {
+      const { PluginManager } = await import('./features/plugins.js');
+      this.plugins = new PluginManager(this);
+      const count = await this.plugins.loadAll();
+      if (count > 0) console.log('  🔌 Plugins: ' + count + ' loaded');
+      await this.plugins.fireHook('onStart', { engine: this });
+    } catch (err) { logger.error('engine', 'Plugins init failed: ' + err.message); }
+
     // Sessions
     try {
       const { SessionManager } = await import('./features/sessions.js');

package/lib/features/plugins.js

@@ -0,0 +1,278 @@
+/**
+ * 🦑 Plugin System
+ * Load/unload plugins dynamically from ~/.squidclaw/plugins/
+ * 
+ * Plugin structure:
+ *   plugins/my-plugin/
+ *     plugin.json    — manifest (name, version, description, hooks)
+ *     index.js       — main entry (exports hooks)
+ *     README.md      — optional docs
+ */
+
+import { logger } from '../core/logger.js';
+import { readdirSync, existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getHome } from '../core/config.js';
+import { pathToFileURL } from 'url';
+
+export class PluginManager {
+  constructor(engine) {
+    this.engine = engine;
+    this.plugins = new Map(); // name -> { manifest, module, status }
+    this.pluginsDir = join(getHome(), 'plugins');
+    mkdirSync(this.pluginsDir, { recursive: true });
+    this._initDb();
+  }
+
+  _initDb() {
+    this.engine.storage.db.exec(`
+      CREATE TABLE IF NOT EXISTS plugins (
+        name TEXT PRIMARY KEY,
+        enabled INTEGER DEFAULT 1,
+        config TEXT DEFAULT '{}',
+        installed_at TEXT DEFAULT (datetime('now'))
+      )
+    `);
+  }
+
+  // ── Load all plugins ──
+
+  async loadAll() {
+    if (!existsSync(this.pluginsDir)) return;
+
+    const dirs = readdirSync(this.pluginsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+
+    let loaded = 0;
+    for (const dir of dirs) {
+      try {
+        await this.load(dir);
+        loaded++;
+      } catch (err) {
+        logger.error('plugins', `Failed to load ${dir}: ${err.message}`);
+      }
+    }
+
+    if (loaded > 0) {
+      logger.info('plugins', `Loaded ${loaded}/${dirs.length} plugins`);
+    }
+    return loaded;
+  }
+
+  // ── Load single plugin ──
+
+  async load(name) {
+    const pluginDir = join(this.pluginsDir, name);
+    const manifestPath = join(pluginDir, 'plugin.json');
+    const indexPath = join(pluginDir, 'index.js');
+
+    if (!existsSync(manifestPath)) {
+      throw new Error('No plugin.json found');
+    }
+
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    manifest.name = manifest.name || name;
+
+    // Check if disabled in DB
+    const dbEntry = this.engine.storage.db.prepare('SELECT * FROM plugins WHERE name = ?').get(manifest.name);
+    if (dbEntry && !dbEntry.enabled) {
+      this.plugins.set(manifest.name, { manifest, module: null, status: 'disabled' });
+      return;
+    }
+
+    // Load module
+    if (!existsSync(indexPath)) {
+      throw new Error('No index.js found');
+    }
+
+    // Dynamic import with cache busting for hot reload
+    const moduleUrl = pathToFileURL(indexPath).href + '?t=' + Date.now();
+    const module = await import(moduleUrl);
+
+    // Register in DB
+    this.engine.storage.db.prepare(
+      'INSERT OR REPLACE INTO plugins (name, enabled, config) VALUES (?, 1, ?)'
+    ).run(manifest.name, JSON.stringify(dbEntry?.config ? JSON.parse(dbEntry.config) : {}));
+
+    // Call onLoad hook
+    if (module.onLoad) {
+      const pluginConfig = dbEntry ? JSON.parse(dbEntry.config || '{}') : {};
+      await module.onLoad({ engine: this.engine, config: pluginConfig, logger });
+    }
+
+    this.plugins.set(manifest.name, { manifest, module, status: 'active', dir: pluginDir });
+    logger.info('plugins', `Loaded: ${manifest.name} v${manifest.version || '?'}`);
+  }
+
+  // ── Unload plugin ──
+
+  async unload(name) {
+    const plugin = this.plugins.get(name);
+    if (!plugin) throw new Error('Plugin not found: ' + name);
+
+    if (plugin.module?.onUnload) {
+      await plugin.module.onUnload({ engine: this.engine });
+    }
+
+    this.plugins.delete(name);
+    logger.info('plugins', `Unloaded: ${name}`);
+  }
+
+  // ── Enable/Disable ──
+
+  enable(name) {
+    this.engine.storage.db.prepare('UPDATE plugins SET enabled = 1 WHERE name = ?').run(name);
+    logger.info('plugins', `Enabled: ${name}`);
+  }
+
+  disable(name) {
+    this.engine.storage.db.prepare('UPDATE plugins SET enabled = 0 WHERE name = ?').run(name);
+    this.unload(name).catch(() => {});
+    logger.info('plugins', `Disabled: ${name}`);
+  }
+
+  // ── Hot reload ──
+
+  async reload(name) {
+    await this.unload(name).catch(() => {});
+    await this.load(name);
+    logger.info('plugins', `Reloaded: ${name}`);
+  }
+
+  // ── Fire hooks ──
+
+  async fireHook(hookName, context) {
+    const results = [];
+    for (const [name, plugin] of this.plugins) {
+      if (plugin.status !== 'active' || !plugin.module) continue;
+
+      const hook = plugin.module[hookName];
+      if (typeof hook === 'function') {
+        try {
+          const result = await hook(context);
+          if (result) results.push({ plugin: name, result });
+        } catch (err) {
+          logger.error('plugins', `${name}.${hookName} failed: ${err.message}`);
+        }
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Hook types:
+   * - onLoad({ engine, config, logger })     — plugin loaded
+   * - onUnload({ engine })                    — plugin unloading
+   * - onMessage({ message, contactId, agentId, metadata, engine }) — incoming message, return { handled, response } to intercept
+   * - onResponse({ response, contactId, agentId, engine })         — before sending response, can modify
+   * - onTool({ toolName, toolArg, agentId, engine })               — custom tool handler, return { result } to handle
+   * - onStart({ engine })                      — engine started
+   * - onStop({ engine })                       — engine stopping
+   * - getTools()                               — return array of tool descriptions for AI prompt
+   */
+
+  // ── Get plugin tool descriptions ──
+
+  getToolDescriptions() {
+    const tools = [];
+    for (const [name, plugin] of this.plugins) {
+      if (plugin.status !== 'active' || !plugin.module?.getTools) continue;
+      try {
+        const pluginTools = plugin.module.getTools();
+        if (Array.isArray(pluginTools)) {
+          tools.push(...pluginTools);
+        }
+      } catch {}
+    }
+    return tools;
+  }
+
+  // ── Handle custom tool calls ──
+
+  async handleTool(toolName, toolArg, agentId) {
+    const results = await this.fireHook('onTool', { toolName, toolArg, agentId, engine: this.engine });
+    if (results.length > 0 && results[0].result) {
+      return results[0].result;
+    }
+    return null;
+  }
+
+  // ── List plugins ──
+
+  list() {
+    return Array.from(this.plugins.entries()).map(([name, p]) => ({
+      name,
+      version: p.manifest.version || '?',
+      description: p.manifest.description || '',
+      status: p.status,
+      hooks: p.module ? Object.keys(p.module).filter(k => k.startsWith('on') || k === 'getTools') : [],
+      author: p.manifest.author || '',
+    }));
+  }
+
+  // ── Create plugin scaffold ──
+
+  scaffold(name, description) {
+    const dir = join(this.pluginsDir, name);
+    mkdirSync(dir, { recursive: true });
+
+    writeFileSync(join(dir, 'plugin.json'), JSON.stringify({
+      name,
+      version: '1.0.0',
+      description: description || 'A Squidclaw plugin',
+      author: '',
+      hooks: ['onMessage', 'onTool', 'getTools'],
+    }, null, 2));
+
+    writeFileSync(join(dir, 'index.js'), `/**
+ * ${name} — Squidclaw Plugin
+ * ${description || ''}
+ */
+
+// Called when plugin loads
+export async function onLoad({ engine, config, logger }) {
+  logger.info('${name}', 'Plugin loaded!');
+}
+
+// Called when plugin unloads
+export async function onUnload({ engine }) {}
+
+// Called on every incoming message — return { handled: true, response } to intercept
+export async function onMessage({ message, contactId, agentId, engine }) {
+  // Example: respond to a specific keyword
+  // if (message.toLowerCase().includes('hello plugin')) {
+  //   return { handled: true, response: 'Hello from ${name} plugin! 🔌' };
+  // }
+  return null;
+}
+
+// Called before response is sent — can modify
+export async function onResponse({ response, contactId, agentId, engine }) {
+  return response; // return modified response or null
+}
+
+// Handle custom tool calls
+export async function onTool({ toolName, toolArg, agentId, engine }) {
+  // if (toolName === 'my_custom_tool') {
+  //   return { result: 'Custom tool result!' };
+  // }
+  return null;
+}
+
+// Return tool descriptions for the AI prompt
+export function getTools() {
+  return [
+    // '### My Custom Tool',
+    // '---TOOL:my_custom_tool:argument---',
+    // 'Description of what this tool does.',
+  ];
+}
+`);
+
+    writeFileSync(join(dir, 'README.md'), `# ${name}\n\n${description || 'A Squidclaw plugin.'}\n\n## Installation\n\nCopy to \`~/.squidclaw/plugins/${name}/\`\n`);
+
+    logger.info('plugins', `Scaffolded: ${dir}`);
+    return dir;
+  }
+}

package/lib/features/sandbox.js

@@ -0,0 +1,299 @@
+/**
+ * 🦑 Proper Sandbox
+ * Isolated code execution with resource limits
+ * - VM isolation (vm module)
+ * - CPU timeout
+ * - Memory limits
+ * - File system jail
+ * - Network restrictions
+ * - Safe eval for user code
+ */
+
+import { logger } from '../core/logger.js';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { join, resolve } from 'path';
+import { execSync, spawn } from 'child_process';
+import vm from 'vm';
+
+export class Sandbox {
+  constructor(options = {}) {
+    this.jailDir = options.jailDir || '/tmp/squidclaw-sandbox';
+    this.timeout = options.timeout || 10000;      // 10s default
+    this.maxMemory = options.maxMemory || 64;      // 64MB
+    this.maxFileSize = options.maxFileSize || 1024 * 1024; // 1MB
+    this.maxFiles = options.maxFiles || 50;
+    this.maxOutputSize = options.maxOutputSize || 50000; // 50KB
+    this.allowNetwork = options.allowNetwork || false;
+    
+    mkdirSync(this.jailDir, { recursive: true });
+
+    // Blocked patterns for shell commands
+    this.blockedCommands = [
+      /rm\s+(-rf?|--recursive)\s+\//, /mkfs/, /dd\s+if=/, /:\(\)\{/, 
+      /chmod\s+777\s+\//, /chown\s.*\//, /passwd/, /userdel/, /useradd/,
+      /shutdown/, /reboot/, /halt/, /poweroff/,
+      /iptables/, /ufw\s/, /firewall/,
+      /wget.*\|.*sh/, /curl.*\|.*sh/, /eval\s*\(/, // download & execute
+      /\/etc\/shadow/, /\/etc\/passwd/,
+      /ssh\s/, /scp\s/, /rsync\s/,  // no remote access
+      /npm\s+install\s+-g/, /pip\s+install/,  // no global installs
+      /systemctl/, /service\s/,  // no service control
+    ];
+  }
+
+  // ── JavaScript VM Execution ──
+
+  evalJS(code, context = {}) {
+    const sandbox = {
+      console: {
+        log: (...args) => { output.push(args.map(String).join(' ')); },
+        error: (...args) => { output.push('ERROR: ' + args.map(String).join(' ')); },
+        warn: (...args) => { output.push('WARN: ' + args.map(String).join(' ')); },
+      },
+      Math, Date, JSON, parseInt, parseFloat, isNaN, isFinite,
+      String, Number, Boolean, Array, Object, Map, Set, RegExp,
+      setTimeout: undefined, setInterval: undefined, // blocked
+      fetch: undefined, // blocked unless allowNetwork
+      require: undefined, // blocked
+      process: { env: {} }, // sanitized
+      Buffer: undefined, // blocked
+      ...context,
+    };
+
+    const output = [];
+
+    try {
+      const vmContext = vm.createContext(sandbox, {
+        codeGeneration: { strings: false, wasm: false },
+      });
+
+      const script = new vm.Script(code, {
+        timeout: this.timeout,
+        filename: 'sandbox.js',
+      });
+
+      const result = script.runInContext(vmContext, {
+        timeout: this.timeout,
+        breakOnSigint: true,
+      });
+
+      if (result !== undefined && !output.length) {
+        output.push(String(result));
+      }
+
+      const finalOutput = output.join('\n').slice(0, this.maxOutputSize);
+      logger.info('sandbox', `JS eval OK (${code.length} chars)`);
+      return { success: true, output: finalOutput, type: 'javascript' };
+
+    } catch (err) {
+      const errMsg = err.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT' 
+        ? 'Execution timeout (' + (this.timeout / 1000) + 's limit)'
+        : err.message;
+      return { success: false, error: errMsg, output: output.join('\n'), type: 'javascript' };
+    }
+  }
+
+  // ── Python Execution (process-isolated) ──
+
+  async runPython(code, options = {}) {
+    const filename = 'run_' + Date.now() + '.py';
+    const filepath = join(this.jailDir, filename);
+    const timeout = options.timeout || this.timeout;
+
+    // Safety: wrap in resource limits
+    const wrappedCode = `
+import sys, os, signal
+signal.alarm(${Math.ceil(timeout / 1000)})
+sys.path = ['.']
+os.chdir('${this.jailDir}')
+${code}
+`;
+
+    writeFileSync(filepath, wrappedCode);
+
+    try {
+      const result = await this._execProcess('python3', [filepath], {
+        timeout,
+        cwd: this.jailDir,
+        maxOutput: this.maxOutputSize,
+      });
+      return { ...result, type: 'python' };
+    } finally {
+      try { unlinkSync(filepath); } catch {}
+    }
+  }
+
+  // ── Shell Execution (sandboxed) ──
+
+  async runShell(command, options = {}) {
+    // Security check
+    for (const pattern of this.blockedCommands) {
+      if (pattern.test(command)) {
+        return { success: false, error: 'Blocked: dangerous command pattern', type: 'shell' };
+      }
+    }
+
+    const timeout = options.timeout || this.timeout;
+
+    try {
+      const output = execSync(command, {
+        cwd: options.cwd || this.jailDir,
+        timeout,
+        maxBuffer: this.maxOutputSize,
+        encoding: 'utf8',
+        env: {
+          PATH: '/usr/local/bin:/usr/bin:/bin',
+          HOME: this.jailDir,
+          LANG: 'en_US.UTF-8',
+          // No AWS keys, no tokens, no secrets
+        },
+      });
+
+      logger.info('sandbox', `Shell OK: ${command.slice(0, 50)}`);
+      return { success: true, output: output.trim().slice(0, this.maxOutputSize), type: 'shell' };
+    } catch (err) {
+      return {
+        success: false,
+        output: (err.stdout || '').trim().slice(0, 5000),
+        error: (err.stderr || err.message).trim().slice(0, 5000),
+        exitCode: err.status || 1,
+        type: 'shell',
+      };
+    }
+  }
+
+  // ── File System (jailed) ──
+
+  writeFile(name, content) {
+    const safePath = this._safePath(name);
+    
+    if (content.length > this.maxFileSize) {
+      throw new Error('File too large: ' + (content.length / 1024).toFixed(0) + 'KB (max ' + (this.maxFileSize / 1024) + 'KB)');
+    }
+
+    const fileCount = this._countFiles();
+    if (fileCount >= this.maxFiles) {
+      throw new Error('Too many files in sandbox (max ' + this.maxFiles + ')');
+    }
+
+    const dir = resolve(safePath, '..');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(safePath, content);
+    return { path: safePath, size: content.length };
+  }
+
+  readFile(name) {
+    const safePath = this._safePath(name);
+    if (!existsSync(safePath)) throw new Error('File not found: ' + name);
+    
+    const stat = statSync(safePath);
+    if (stat.size > this.maxFileSize) throw new Error('File too large to read');
+    
+    return readFileSync(safePath, 'utf8');
+  }
+
+  listFiles(subdir = '.') {
+    const safePath = this._safePath(subdir);
+    if (!existsSync(safePath)) return [];
+    
+    return readdirSync(safePath, { withFileTypes: true }).map(d => ({
+      name: d.name,
+      type: d.isDirectory() ? 'dir' : 'file',
+      size: d.isFile() ? statSync(join(safePath, d.name)).size : 0,
+    }));
+  }
+
+  deleteFile(name) {
+    const safePath = this._safePath(name);
+    if (existsSync(safePath)) unlinkSync(safePath);
+  }
+
+  // ── Cleanup ──
+
+  cleanup() {
+    try {
+      execSync(`find ${this.jailDir} -type f -mmin +60 -delete 2>/dev/null`, { timeout: 5000 });
+      logger.info('sandbox', 'Cleaned old files');
+    } catch {}
+  }
+
+  // ── Stats ──
+
+  getStats() {
+    const files = this._countFiles();
+    let totalSize = 0;
+    try {
+      const output = execSync(`du -sb ${this.jailDir} 2>/dev/null`, { encoding: 'utf8' });
+      totalSize = parseInt(output.split('\t')[0]) || 0;
+    } catch {}
+
+    return {
+      files,
+      maxFiles: this.maxFiles,
+      totalSize,
+      maxFileSize: this.maxFileSize,
+      timeout: this.timeout,
+      maxMemory: this.maxMemory,
+      jailDir: this.jailDir,
+      allowNetwork: this.allowNetwork,
+    };
+  }
+
+  // ── Internal ──
+
+  _safePath(name) {
+    const resolved = resolve(this.jailDir, name);
+    if (!resolved.startsWith(this.jailDir)) {
+      throw new Error('Path traversal blocked');
+    }
+    return resolved;
+  }
+
+  _countFiles() {
+    try {
+      const output = execSync(`find ${this.jailDir} -type f | wc -l`, { encoding: 'utf8', timeout: 3000 });
+      return parseInt(output.trim()) || 0;
+    } catch { return 0; }
+  }
+
+  async _execProcess(cmd, args, options = {}) {
+    return new Promise((resolve) => {
+      let stdout = '';
+      let stderr = '';
+      const timeout = options.timeout || this.timeout;
+      const maxOutput = options.maxOutput || this.maxOutputSize;
+
+      const proc = spawn(cmd, args, {
+        cwd: options.cwd || this.jailDir,
+        timeout,
+        env: {
+          PATH: '/usr/local/bin:/usr/bin:/bin',
+          HOME: this.jailDir,
+          LANG: 'en_US.UTF-8',
+        },
+      });
+
+      const timer = setTimeout(() => {
+        proc.kill('SIGKILL');
+        resolve({ success: false, error: 'Timeout (' + (timeout / 1000) + 's)', output: stdout.slice(0, maxOutput) });
+      }, timeout);
+
+      proc.stdout.on('data', d => { stdout += d; if (stdout.length > maxOutput) proc.kill(); });
+      proc.stderr.on('data', d => { stderr += d; });
+
+      proc.on('close', (code) => {
+        clearTimeout(timer);
+        if (code === 0) {
+          resolve({ success: true, output: stdout.trim().slice(0, maxOutput) });
+        } else {
+          resolve({ success: false, output: stdout.trim().slice(0, 5000), error: stderr.trim().slice(0, 5000), exitCode: code });
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timer);
+        resolve({ success: false, error: err.message });
+      });
+    });
+  }
+}

package/lib/middleware/commands.js

@@ -145,6 +145,106 @@ export async function commandsMiddleware(ctx, next) {
     return;
   }
 
+  if (cmd === '/sandbox') {
+    if (!ctx.engine.sandbox) { await ctx.reply('❌ Sandbox not available'); return; }
+    const args = msg.slice(9).trim();
+    
+    if (!args || args === 'stats') {
+      const stats = ctx.engine.sandbox.getStats();
+      await ctx.reply('🔒 *Sandbox*\n\n📁 Files: ' + stats.files + '/' + stats.maxFiles + '\n💾 Size: ' + (stats.totalSize / 1024).toFixed(0) + ' KB\n⏱️ Timeout: ' + (stats.timeout / 1000) + 's\n🧠 Max memory: ' + stats.maxMemory + ' MB\n🌐 Network: ' + (stats.allowNetwork ? '✅' : '🚫'));
+      return;
+    }
+    
+    if (args === 'files') {
+      const files = ctx.engine.sandbox.listFiles();
+      if (files.length === 0) { await ctx.reply('📁 Sandbox is empty'); return; }
+      const lines = files.map(f => (f.type === 'dir' ? '📁 ' : '📄 ') + f.name + (f.size ? ' (' + (f.size / 1024).toFixed(1) + ' KB)' : ''));
+      await ctx.reply('📁 *Sandbox Files*\n\n' + lines.join('\n'));
+      return;
+    }
+    
+    if (args === 'clean') {
+      ctx.engine.sandbox.cleanup();
+      await ctx.reply('🧹 Sandbox cleaned');
+      return;
+    }
+    
+    if (args.startsWith('js ')) {
+      const code = args.slice(3);
+      const result = ctx.engine.sandbox.evalJS(code);
+      await ctx.reply(result.success ? '```\n' + (result.output || '(no output)') + '\n```' : '❌ ' + result.error);
+      return;
+    }
+    
+    if (args.startsWith('py ')) {
+      const code = args.slice(3);
+      const result = await ctx.engine.sandbox.runPython(code);
+      await ctx.reply(result.success ? '```\n' + (result.output || '(no output)') + '\n```' : '❌ ' + (result.error || 'Failed'));
+      return;
+    }
+
+    await ctx.reply('🔒 *Sandbox Commands*\n\n/sandbox — stats\n/sandbox files — list files\n/sandbox clean — remove old files\n/sandbox js <code> — run JavaScript\n/sandbox py <code> — run Python');
+    return;
+  }
+
+  if (cmd === '/plugins' || cmd === '/plugin') {
+    if (!ctx.engine.plugins) { await ctx.reply('❌ Plugin system not available'); return; }
+    const args = msg.split(/\s+/).slice(1);
+    const sub = args[0];
+
+    if (!sub || sub === 'list') {
+      const plugins = ctx.engine.plugins.list();
+      if (plugins.length === 0) {
+        await ctx.reply('🔌 No plugins installed\n\nCreate one: /plugin new <name>\nOr drop a plugin folder in ~/.squidclaw/plugins/');
+        return;
+      }
+      const lines = plugins.map(p =>
+        (p.status === 'active' ? '🟢' : '⏸️') + ' *' + p.name + '* v' + p.version + '\n   ' + p.description + '\n   Hooks: ' + p.hooks.join(', ')
+      );
+      await ctx.reply('🔌 *Plugins*\n\n' + lines.join('\n\n'));
+      return;
+    }
+
+    if (sub === 'new' || sub === 'create') {
+      const name = args[1] || 'my-plugin';
+      const desc = args.slice(2).join(' ') || '';
+      const dir = ctx.engine.plugins.scaffold(name, desc);
+      await ctx.reply('🔌 Plugin scaffolded!\n\n📁 ' + dir + '\n\nEdit index.js to add your logic, then /plugin reload ' + name);
+      return;
+    }
+
+    if (sub === 'reload') {
+      const name = args[1];
+      if (!name) { await ctx.reply('Usage: /plugin reload <name>'); return; }
+      try {
+        await ctx.engine.plugins.reload(name);
+        await ctx.reply('🔌 Reloaded: ' + name);
+      } catch (err) { await ctx.reply('❌ ' + err.message); }
+      return;
+    }
+
+    if (sub === 'enable') {
+      ctx.engine.plugins.enable(args[1]);
+      await ctx.reply('✅ Enabled: ' + args[1]);
+      return;
+    }
+
+    if (sub === 'disable') {
+      ctx.engine.plugins.disable(args[1]);
+      await ctx.reply('⏸️ Disabled: ' + args[1]);
+      return;
+    }
+
+    if (sub === 'unload') {
+      await ctx.engine.plugins.unload(args[1]);
+      await ctx.reply('🔌 Unloaded: ' + args[1]);
+      return;
+    }
+
+    await ctx.reply('🔌 *Plugin Commands*\n\n/plugin list — show plugins\n/plugin new <name> — create plugin\n/plugin reload <name> — hot reload\n/plugin enable <name>\n/plugin disable <name>');
+    return;
+  }
+
   if (cmd === '/sessions') {
     if (!ctx.engine.sessions) { await ctx.reply('❌ Sessions not available'); return; }
     const args = msg.slice(10).trim();

package/lib/middleware/plugins.js

@@ -0,0 +1,41 @@
+/**
+ * Plugin middleware — fires onMessage hook before AI processing
+ */
+export async function pluginMiddleware(ctx, next) {
+  if (!ctx.engine.plugins) { await next(); return; }
+
+  // Fire onMessage hooks
+  const results = await ctx.engine.plugins.fireHook('onMessage', {
+    message: ctx.message,
+    contactId: ctx.contactId,
+    agentId: ctx.agentId,
+    metadata: ctx.metadata,
+    engine: ctx.engine,
+  });
+
+  // Check if any plugin handled it
+  for (const r of results) {
+    if (r.result?.handled) {
+      ctx.response = {
+        messages: [r.result.response],
+        reaction: r.result.reaction || null,
+      };
+      ctx.handled = true;
+      // Skip to response sender
+      await next();
+      return;
+    }
+  }
+
+  await next();
+
+  // Fire onResponse hooks (post-AI)
+  if (ctx.response) {
+    await ctx.engine.plugins.fireHook('onResponse', {
+      response: ctx.response,
+      contactId: ctx.contactId,
+      agentId: ctx.agentId,
+      engine: ctx.engine,
+    });
+  }
+}

package/lib/tools/router.js

@@ -169,6 +169,13 @@ export class ToolRouter {
       '---TOOL:handoff:reason---',
       'Transfer the conversation to a human agent. Use when you cannot help further.');
 
+    tools.push('', '### Run JavaScript (Sandboxed)',
+      '---TOOL:js:console.log(2 + 2)---',
+      'Execute JavaScript in a secure VM sandbox. No network, no filesystem, no require. Safe for math, logic, data processing.',
+      '', '### Sandbox Info',
+      '---TOOL:sandbox_info:stats---',
+      'Show sandbox stats (files, size, limits).');
+
     tools.push('', '### Run Command',
       '---TOOL:exec:ls -la---',
       'Execute a shell command. Output is returned. Sandboxed for safety.',
@@ -244,6 +251,15 @@ export class ToolRouter {
 
     tools.push('', '**Important:** Use tools when needed. The tool result will be injected into the conversation automatically. Only use one tool per response.');
 
+    // Plugin tools
+    if (this._engine?.plugins) {
+      const pluginTools = this._engine.plugins.getToolDescriptions();
+      if (pluginTools.length > 0) {
+        tools.push('', '## Plugin Tools');
+        tools.push(...pluginTools);
+      }
+    }
+
     return tools.join('\n');
   }
 
@@ -602,10 +618,15 @@ export class ToolRouter {
         case 'exec':
         case 'shell':
         case 'run': {
-          const { ShellTool } = await import('./shell.js');
-          const sh = new ShellTool();
-          const result = sh.exec(toolArg);
-          toolResult = result.error ? 'Error: ' + result.error : result.output || '(no output)';
+          if (this._engine?.sandbox) {
+            const result = await this._engine.sandbox.runShell(toolArg);
+            toolResult = result.success ? (result.output || '(no output)') : 'Error: ' + (result.error || 'Unknown');
+          } else {
+            const { ShellTool } = await import('./shell.js');
+            const sh = new ShellTool();
+            const result = sh.exec(toolArg);
+            toolResult = result.error ? 'Error: ' + result.error : result.output || '(no output)';
+          }
           break;
         }
         case 'readfile': {
@@ -634,14 +655,44 @@ export class ToolRouter {
           toolResult = result.error || result.files.map(f => (f.type === 'dir' ? '📁 ' : '📄 ') + f.name).join('\n');
           break;
         }
+        case 'js':
+        case 'javascript':
+        case 'eval': {
+          if (this._engine?.sandbox) {
+            const result = this._engine.sandbox.evalJS(toolArg);
+            toolResult = result.success ? (result.output || '(no output)') : 'Error: ' + (result.error || 'Unknown');
+          } else {
+            toolResult = 'Sandbox not available';
+          }
+          break;
+        }
         case 'python':
         case 'py': {
-          const { ShellTool } = await import('./shell.js');
-          const sh = new ShellTool();
-          // Write Python script then execute
-          sh.writeFile('_run.py', toolArg);
-          const result = sh.exec('python3 _run.py');
-          toolResult = result.error ? 'Error: ' + result.error : result.output || '(no output)';
+          if (this._engine?.sandbox) {
+            const result = await this._engine.sandbox.runPython(toolArg);
+            toolResult = result.success ? (result.output || '(no output)') : 'Error: ' + (result.error || 'Unknown');
+          } else {
+            const { ShellTool } = await import('./shell.js');
+            const sh = new ShellTool();
+            sh.writeFile('_run.py', toolArg);
+            const result = sh.exec('python3 _run.py');
+            toolResult = result.error ? 'Error: ' + result.error : result.output || '(no output)';
+          }
+          break;
+        }
+        case 'sandbox_info': {
+          if (this._engine?.sandbox) {
+            const stats = this._engine.sandbox.getStats();
+            toolResult = '🔒 Sandbox Stats:\n' +
+              '📁 Files: ' + stats.files + '/' + stats.maxFiles + '\n' +
+              '💾 Size: ' + (stats.totalSize / 1024).toFixed(0) + ' KB\n' +
+              '⏱️ Timeout: ' + (stats.timeout / 1000) + 's\n' +
+              '🧠 Max memory: ' + stats.maxMemory + ' MB\n' +
+              '🌐 Network: ' + (stats.allowNetwork ? 'allowed' : 'blocked') + '\n' +
+              '📂 Jail: ' + stats.jailDir;
+          } else {
+            toolResult = 'Sandbox not available';
+          }
           break;
         }
         case 'spawn': {
@@ -805,7 +856,19 @@ export class ToolRouter {
           toolResult = `Email sent to ${to}`;
           break;
 
-        default:
+        default: {
+          // Check plugins for custom tool handlers
+          if (this._engine?.plugins) {
+            const pluginResult = await this._engine.plugins.handleTool(toolName, toolArg, agentId);
+            if (pluginResult) {
+              if (pluginResult.filePath) {
+                return { toolUsed: true, toolName, toolResult: pluginResult.result || 'Done', filePath: pluginResult.filePath, fileName: pluginResult.fileName, cleanResponse };
+              }
+              toolResult = pluginResult.result || pluginResult;
+              break;
+            }
+          }
+        }
           toolResult = `Unknown tool: ${toolName}`;
       }
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squidclaw",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "🦑 AI agent platform — human-like agents for WhatsApp, Telegram & more",
   "main": "lib/engine.js",
   "bin": {