shoud-cli 1.0.0 → 1.0.2

package/bin/shoud.js

@@ -1,22 +1,23 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
+
 const { program } = require('commander');
 const chalk = require('chalk');
 const { login } = require('../src/auth/deviceFlow');
 const { executeTask } = require('../src/runtime/agentLoop');
 
-// ─── Banner Art ───────────────────────────────────────────────
+// ─── Exact SHOUD Banner Art (provided by user) ──────────────────────────────
 const BANNER_ART = [
-  "  ███████╗██╗  ██╗ ██████╗ ██████╗ ███████╗██╗   ██╗██╗   ██╗██████╗",
-  "  ██╔════╝██║  ██║██╔═══██╗██╔══██╗██╔════╝██║   ██║██║   ██║██╔══██╗",
-  "  ███████╗███████║██║   ██║██║  ██║███████╗██║   ██║██║   ██║██████╔╝",
-  "  ╚════██║██╔══██║██║   ██║██║  ██║╚════██║██║   ██║██║   ██║██╔══██╗",
-  "  ███████║██║  ██║╚██████╔╝██████╔╝███████║╚██████╔╝╚██████╔╝██║  ██║",
-  "  ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝"
+  "  ███████╗██╗  ██╗ ██████╗ ██╗   ██╗██████╗ ",
+  "  ██╔════╝██║  ██║██╔═══██╗██║   ██║██╔══██╗",
+  "  ███████╗███████║██║   ██║██║   ██║██║  ██║",
+  "  ╚════██║██╔══██║██║   ██║██║   ██║██║  ██║",
+  "  ███████║██║  ██║╚██████╔╝╚██████╔╝██████╔╝",
+  "  ╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═════╝ "
 ];
 
 const SLEEP = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-// ─── Animated Banner ──────────────────────────────────────────
+// ─── Animated Banner ─────────────────────────────────────────────────────────
 async function renderAnimatedBanner() {
   if (!process.stdout.isTTY) {
     console.log(chalk.hex('#B5F96C')(BANNER_ART.join('\n')));
@@ -44,13 +45,13 @@ async function renderAnimatedBanner() {
 
     console.log(
       chalk.hex('#3B472E')(
-        '  ┌──────────────────────────────────────────────────────┐\n' +
+        '  ┌──────────────────────────────────────────────────────────┐\n' +
         '  │'
       ) +
       chalk.hex('#B5F96C').bold('          Give your computer a job.           ') +
       chalk.hex('#3B472E')(
         '│\n' +
-        '  └──────────────────────────────────────────────────────┘\n'
+        '  └──────────────────────────────────────────────────────────┘\n'
       )
     );
 
@@ -60,15 +61,16 @@ async function renderAnimatedBanner() {
   process.stdout.write('\x1B[?25h');
 }
 
-// ─── Custom Help ──────────────────────────────────────────────
+// ─── Custom Help ──────────────────────────────────────────────────────────────
 async function customHelp() {
   console.log(chalk.hex('#B5F96C').bold('\n  SHOUD Terminal Agent - Command Reference\n'));
   console.log(chalk.gray('  Usage: shoud [command] OR shoud "[prompt]"\n'));
 
   console.log(chalk.white.bold('  Commands:'));
   console.log(`    ${chalk.hex('#B5F96C')('shoud login')}     Authenticate this device with your Google account.`);
-  console.log(`    ${chalk.hex('#B5F96C')('shoud help')}      Display this beautiful help menu.`);
-  console.log(`    ${chalk.hex('#B5F96C')('shoud status')}    Check your current credit balance and active plan.\n`);
+  console.log(`    ${chalk.hex('#B5F96C')('shoud help')}      Display this help menu.`);
+  console.log(`    ${chalk.hex('#B5F96C')('shoud status')}    Check your current credit balance and active plan.`);
+  console.log(`    ${chalk.hex('#B5F96C')('shoud --version')} Show the version number.\n`);
 
   console.log(chalk.white.bold('  Autonomous Execution:'));
   console.log(chalk.gray('    Wrap your instructions in quotes to trigger the agent loop.'));
@@ -76,12 +78,20 @@ async function customHelp() {
   console.log(`    ${chalk.hex('#B5F96C')('>')} shoud "Run npm test and fix any failing test cases"\n`);
 }
 
-// ─── Main ─────────────────────────────────────────────────────
+// ─── Main ──────────────────────────────────────────────────────────────────────
 async function main() {
   const args = process.argv.slice(2);
 
-  // Intercept help commands and empty input
-  if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {
+  // Intercept help, version, and empty input
+  if (args.length === 0 ||
+      args[0] === 'help' || args[0] === '--help' || args[0] === '-h' ||
+      args[0] === '--version' || args[0] === '-v') {
+    if (args[0] === '--version' || args[0] === '-v') {
+      // Let Commander handle version
+      program.version('1.0.0');
+      program.parse(process.argv);
+      return;
+    }
     await renderAnimatedBanner();
     await customHelp();
     return;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "shoud-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "SHOUD Terminal Agent: Give your computer a job.",
   "main": "bin/shoud.js",
   "bin": {
-    "shoud": "./bin/shoud.js"
+    "shoud": "bin/shoud.js"
   },
   "scripts": {
     "start": "node ./bin/shoud.js"
@@ -19,5 +19,17 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "install.sh",
+    "!**/*.test.js",
+    "!**/*.spec.js"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/shoud-monorepo.git"
   }
 }

package/src/auth/deviceFlow.js

@@ -5,36 +5,139 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const SESSION_FILE = path.join(os.homedir(), '.shoud_session');
+// Use a dedicated config directory
+const CONFIG_DIR = path.join(os.homedir(), '.shoud');
+const SESSION_FILE = path.join(CONFIG_DIR, 'session.json');
 
+// Ensure config directory exists with secure permissions
+if (!fs.existsSync(CONFIG_DIR)) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+/**
+ * Decode a JWT token (without verification) to extract payload
+ */
+function decodeJWT(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = Buffer.from(parts[1], 'base64').toString('utf-8');
+    return JSON.parse(payload);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Write token to session file with expiry
+ */
+function saveToken(token) {
+  const payload = decodeJWT(token);
+  const expiresAt = payload?.exp ? payload.exp * 1000 : null; // convert to milliseconds
+  const data = {
+    token,
+    expiresAt,
+    createdAt: Date.now()
+  };
+  try {
+    fs.writeFileSync(SESSION_FILE, JSON.stringify(data, null, 2), {
+      encoding: 'utf-8',
+      mode: 0o600
+    });
+  } catch (err) {
+    console.error(chalk.red(`Failed to save session: ${err.message}`));
+    throw err;
+  }
+}
+
+/**
+ * Retrieve token if present and not expired
+ */
+function getToken() {
+  if (!fs.existsSync(SESSION_FILE)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(SESSION_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    const { token, expiresAt } = data;
+
+    if (!token) return null;
+
+    // If we have an expiry and it's in the past, token is invalid
+    if (expiresAt && Date.now() >= expiresAt) {
+      // Optionally delete the stale file
+      fs.unlinkSync(SESSION_FILE);
+      return null;
+    }
+
+    // If we don't have expiry, we can still try to decode now to check
+    if (!expiresAt) {
+      const payload = decodeJWT(token);
+      if (payload?.exp) {
+        const expMs = payload.exp * 1000;
+        if (Date.now() >= expMs) {
+          fs.unlinkSync(SESSION_FILE);
+          return null;
+        }
+      }
+    }
+
+    return token;
+  } catch (_) {
+    // Corrupted or invalid file, delete it
+    try { fs.unlinkSync(SESSION_FILE); } catch (_) {}
+    return null;
+  }
+}
+
+/**
+ * Login flow: open browser, ask for token, save it
+ */
 async function login() {
   console.log(chalk.cyan('Opening browser to sign in via shoud.online...'));
   await open('https://shoud.online/login');
-  
+
   console.log(chalk.gray('\nOnce signed in, copy your session token from the browser.'));
-  
+
   const { token } = await inquirer.prompt([
     {
       type: 'password',
       name: 'token',
       message: 'Paste your session token:',
-      mask: '*'
+      mask: '*',
+      validate: (input) => {
+        if (!input || input.trim().length === 0) {
+          return 'Token cannot be empty.';
+        }
+        // Simple validation: check if it looks like a JWT (three parts)
+        const parts = input.trim().split('.');
+        if (parts.length !== 3) {
+          return 'Invalid token format. Please paste the full token from the browser.';
+        }
+        return true;
+      }
     }
   ]);
 
   if (token) {
-    fs.writeFileSync(SESSION_FILE, token, { encoding: 'utf-8', mode: 0o600 });
+    saveToken(token.trim());
     console.log(chalk.green('\n✓ Signed in successfully. Device connected.'));
   } else {
-    console.log(chalk.red('\nLogin failed: No token provided.'));
+    console.log(chalk.red('\nLogin cancelled.'));
   }
 }
 
-function getToken() {
-  if (!fs.existsSync(SESSION_FILE)) {
-    return null;
-  }
-  return fs.readFileSync(SESSION_FILE, 'utf-8').trim();
+/**
+ * Validate token by checking with the backend (optional, can be used before API calls)
+ * For now, we just rely on getToken() returning null if expired.
+ */
+async function validateToken() {
+  const token = getToken();
+  if (!token) return false;
+  // Could make a lightweight request to backend to verify (e.g., /auth/verify)
+  // but we assume token is valid if not expired.
+  return true;
 }
 
-module.exports = { login, getToken };
+module.exports = { login, getToken, validateToken, saveToken };

package/src/context/checkpoint.js

@@ -1,22 +1,81 @@
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
-const CHECKPOINT_FILE = path.join(process.cwd(), '.shoud_checkpoint.json');
+const CONFIG_DIR = path.join(os.homedir(), '.shoud');
+const CHECKPOINT_FILE = path.join(CONFIG_DIR, 'checkpoint.json');
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+// Ensure config directory exists with secure permissions
+if (!fs.existsSync(CONFIG_DIR)) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+/**
+ * Save the execution state (messages, etc.) to a checkpoint file.
+ * Includes a timestamp for TTL.
+ */
 function saveCheckpoint(state) {
-  fs.writeFileSync(CHECKPOINT_FILE, JSON.stringify(state, null, 2));
+  try {
+    const data = {
+      timestamp: Date.now(),
+      ...state
+    };
+    fs.writeFileSync(CHECKPOINT_FILE, JSON.stringify(data, null, 2), {
+      encoding: 'utf-8',
+      mode: 0o600
+    });
+  } catch (err) {
+    console.error(`Failed to save checkpoint: ${err.message}`);
+    // We don't throw; the agent can continue without checkpointing
+  }
 }
 
+/**
+ * Load a checkpoint if it exists and is not too old.
+ * Returns the state object (e.g., { messages }) or null if none or expired.
+ */
 function loadCheckpoint() {
-  if (fs.existsSync(CHECKPOINT_FILE)) {
-    return JSON.parse(fs.readFileSync(CHECKPOINT_FILE, 'utf-8'));
+  if (!fs.existsSync(CHECKPOINT_FILE)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(CHECKPOINT_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    const { timestamp, ...state } = data;
+
+    // Check TTL
+    if (timestamp && (Date.now() - timestamp) > MAX_AGE_MS) {
+      // Stale checkpoint – delete it and ignore
+      clearCheckpoint();
+      return null;
+    }
+
+    // Validate that the state contains at least a messages array
+    if (!state.messages || !Array.isArray(state.messages)) {
+      // Corrupted or invalid state; delete it
+      clearCheckpoint();
+      return null;
+    }
+
+    return state;
+  } catch (err) {
+    // If file is corrupt, delete it
+    clearCheckpoint();
+    return null;
   }
-  return null;
 }
 
+/**
+ * Clear (delete) the checkpoint file.
+ */
 function clearCheckpoint() {
   if (fs.existsSync(CHECKPOINT_FILE)) {
-    fs.unlinkSync(CHECKPOINT_FILE);
+    try {
+      fs.unlinkSync(CHECKPOINT_FILE);
+    } catch (_) {
+      // Ignore errors during cleanup
+    }
   }
 }
 

package/src/permissions/engine.js

@@ -1,20 +1,85 @@
 const inquirer = require('inquirer');
 const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 
-// In a full implementation, this could read from a .shoudignore or local config
-const alwaysAllowedCommands = new Set(['ls', 'pwd', 'git status']);
+const CONFIG_DIR = path.join(os.homedir(), '.shoud');
+const ALLOWLIST_FILE = path.join(CONFIG_DIR, 'allowlist.json');
 
-async function verifyPermission(toolName, input) {
-  if (toolName === 'read_file') return true; // Safe operation
-  
-  const commandContext = input.command || input.path || 'unknown';
+// Ensure config directory exists
+if (!fs.existsSync(CONFIG_DIR)) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
 
-  if (toolName === 'execute_shell' && alwaysAllowedCommands.has(commandContext)) {
-    return true;
+// Load persistent allowlist (or create empty)
+function loadAllowlist() {
+  try {
+    if (fs.existsSync(ALLOWLIST_FILE)) {
+      return JSON.parse(fs.readFileSync(ALLOWLIST_FILE, 'utf-8'));
+    }
+  } catch (_) {}
+  return { commands: [], paths: [] };
+}
+
+// Save allowlist
+function saveAllowlist(data) {
+  try {
+    fs.writeFileSync(ALLOWLIST_FILE, JSON.stringify(data, null, 2), {
+      encoding: 'utf-8',
+      mode: 0o600
+    });
+  } catch (_) {}
+}
+
+// In‑memory session allowlist (cleared on CLI restart)
+let sessionAllowList = {
+  commands: new Set(),
+  paths: new Set()
+};
+
+/**
+ * Check if a command is allowed by persistent or session allowlists.
+ */
+function isAllowed(toolName, input) {
+  if (toolName === 'read_file') return true; // always safe
+
+  if (toolName === 'execute_shell') {
+    const cmd = input.command?.trim().split(/\s+/)[0] || '';
+    // Persistent allowlist
+    const persistent = loadAllowlist();
+    if (persistent.commands.includes(cmd)) return true;
+    // Session allowlist
+    if (sessionAllowList.commands.has(cmd)) return true;
   }
 
+  if (toolName === 'write_file' || toolName === 'read_file') {
+    const filePath = input.path || '';
+    // Check persistent and session for paths (exact match or prefix)
+    // For simplicity, we'll just match exact paths; could be extended
+    const persistent = loadAllowlist();
+    if (persistent.paths.includes(filePath)) return true;
+    if (sessionAllowList.paths.has(filePath)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Prompt user for permission, with options for session‑wide or persistent allow.
+ */
+async function verifyPermission(toolName, input) {
+  // If already allowed, skip prompt
+  if (isAllowed(toolName, input)) return true;
+
+  // Build display info
+  let target = '';
+  if (toolName === 'execute_shell') target = input.command || 'unknown command';
+  else if (toolName === 'read_file' || toolName === 'write_file') target = input.path || 'unknown path';
+  else target = JSON.stringify(input);
+
   console.log(chalk.yellow(`\n⚠ SHOUD requests permission to run: ${chalk.bold(toolName)}`));
-  console.log(chalk.gray(`Target: ${commandContext}`));
+  console.log(chalk.gray(`Target: ${target}`));
 
   const { permission } = await inquirer.prompt([
     {
@@ -23,12 +88,46 @@ async function verifyPermission(toolName, input) {
       message: 'Allow this operation?',
       choices: [
         { name: 'Allow once', value: 'once' },
+        { name: 'Allow for this session', value: 'session' },
+        { name: 'Always allow (save to config)', value: 'always' },
         { name: 'Deny', value: 'deny' }
       ]
     }
   ]);
 
-  return permission === 'once';
+  if (permission === 'deny') return false;
+
+  // Add to session allowlist if requested
+  if (permission === 'session') {
+    if (toolName === 'execute_shell') {
+      const cmd = input.command.trim().split(/\s+/)[0];
+      sessionAllowList.commands.add(cmd);
+    } else if (toolName === 'read_file' || toolName === 'write_file') {
+      sessionAllowList.paths.add(input.path);
+    }
+    return true;
+  }
+
+  // Add to persistent allowlist
+  if (permission === 'always') {
+    const allowlist = loadAllowlist();
+    if (toolName === 'execute_shell') {
+      const cmd = input.command.trim().split(/\s+/)[0];
+      if (!allowlist.commands.includes(cmd)) {
+        allowlist.commands.push(cmd);
+        saveAllowlist(allowlist);
+      }
+    } else if (toolName === 'read_file' || toolName === 'write_file') {
+      if (!allowlist.paths.includes(input.path)) {
+        allowlist.paths.push(input.path);
+        saveAllowlist(allowlist);
+      }
+    }
+    return true;
+  }
+
+  // Once
+  return true;
 }
 
 module.exports = { verifyPermission };

package/src/runtime/agentLoop.js

@@ -8,6 +8,7 @@ const { executeTool } = require('../tools/index');
 const { saveCheckpoint, loadCheckpoint, clearCheckpoint } = require('../context/checkpoint');
 
 const API_URL = process.env.SHOUD_API_URL || 'https://shoud.online/api';
+const BILLING_URL = process.env.SHOUD_BILLING_URL || 'https://shoud.vantyrixtek.online';
 
 async function executeTask(prompt) {
   const token = getToken();
@@ -33,70 +34,95 @@ async function executeTask(prompt) {
     try {
       const response = await axios.post(`${API_URL}/agent/infer`, {
         messages,
-        estimatedBudget: 0.10 // 10 cents max budget per loop iteration
+        systemPrompt: undefined // optional, can be passed via CLI flag if needed
       }, {
         headers: { Authorization: `Bearer ${token}` }
       });
 
       const aiMessage = response.data;
+
+      // Validate response structure
+      if (!aiMessage || !aiMessage.content || !Array.isArray(aiMessage.content)) {
+        throw new Error('Invalid response from SHOUD agent.');
+      }
+
+      // Add assistant message to conversation history
       messages.push({ role: 'assistant', content: aiMessage.content });
       spinner.stop();
 
+      // Check if the assistant used a tool
       if (aiMessage.stop_reason === 'tool_use') {
         for (const block of aiMessage.content) {
           if (block.type === 'tool_use') {
             console.log(chalk.blue(`\n● Agent requested: ${block.name}`));
-            
+
             const isAllowed = await verifyPermission(block.name, block.input);
             let toolResult = '';
 
             if (isAllowed) {
               spinner.start(`Executing ${block.name}...`);
-              toolResult = executeTool(block.name, block.input);
-              spinner.stop();
-              console.log(chalk.green(`✓ Tool executed.`));
+              try {
+                toolResult = executeTool(block.name, block.input);
+                spinner.stop();
+                console.log(chalk.green(`✓ Tool executed.`));
+              } catch (toolError) {
+                spinner.stop();
+                console.log(chalk.red(`✕ Tool execution failed: ${toolError.message}`));
+                toolResult = `Error: ${toolError.message}`;
+              }
             } else {
-              toolResult = "User denied permission to execute this tool.";
+              toolResult = 'User denied permission to execute this tool.';
               console.log(chalk.red(`✕ Permission denied.`));
             }
 
+            // Send tool result back to the agent
             messages.push({
               role: 'user',
               content: [{ type: 'tool_result', tool_use_id: block.id, content: toolResult }]
             });
-            
-            // Save state after tool execution
+
+            // Save checkpoint after each tool interaction
             saveCheckpoint({ messages });
           }
         }
         spinner.start('Analyzing tool results...');
       } else {
-        // Task completed normally
+        // Task completed (no more tool calls)
         taskComplete = true;
         clearCheckpoint();
-        
-        // Print the final text block from Claude
-        const finalResponse = aiMessage.content.find(c => c.type === 'text')?.text || 'Done.';
+
+        // Extract the final text response
+        const textBlocks = aiMessage.content.filter(c => c.type === 'text');
+        const finalResponse = textBlocks.length > 0
+          ? textBlocks.map(t => t.text).join('\n')
+          : 'Task completed.';
+
         console.log(chalk.green('\n✓ Task Complete.\n'));
         console.log(chalk.white(finalResponse));
       }
 
     } catch (error) {
       spinner.stop();
+
+      // Handle insufficient funds (402) specifically
       if (error.response && error.response.status === 402) {
+        const balance = error.response.data.balance || 0;
         console.log(chalk.red('\n⏸ Task paused. Insufficient SHOUD Credits.'));
-        console.log(chalk.gray(`Balance: $${error.response.data.balance.toFixed(4)}`));
+        console.log(chalk.gray(`Balance: $${balance.toFixed(4)}`));
+        // Save checkpoint so the user can resume later
         saveCheckpoint({ messages });
-        
+
         console.log(chalk.cyan('Opening browser to add credits...'));
-        await open('https://shoud.vantyrixtek.online/?amount=10');
+        await open(`${BILLING_URL}/?amount=10`);
         console.log(chalk.gray('Run your command again once credits are added to resume.'));
         return;
-      } else {
-        console.log(chalk.red(`\nError: ${error.response?.data?.error || error.message}`));
-        saveCheckpoint({ messages });
-        return;
       }
+
+      // Generic error
+      console.log(chalk.red(`\nError: ${error.response?.data?.error || error.message}`));
+      // Save checkpoint to preserve progress
+      saveCheckpoint({ messages });
+      return;
     }
   }
 }

package/src/tools/index.js

@@ -1,20 +1,128 @@
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const fs = require('fs');
+const path = require('path');
 
-function executeTool(toolName, input) {
+// Allowed shell commands (whitelist)
+const ALLOWED_COMMANDS = new Set([
+  'ls', 'pwd', 'cat', 'grep', 'find', 'echo',
+  'mkdir', 'rmdir', 'touch', 'head', 'tail',
+  'wc', 'sort', 'uniq', 'diff', 'patch',
+  'git' // optional, but careful
+]);
+
+// Maximum output size (1 MB)
+const MAX_OUTPUT_SIZE = 1024 * 1024;
+
+// Get the project root (current working directory where CLI was started)
+const PROJECT_ROOT = process.cwd();
+
+/**
+ * Sanitize a file path to ensure it stays within the project root.
+ */
+function sanitizePath(inputPath) {
+  // Resolve relative paths
+  const resolved = path.resolve(PROJECT_ROOT, inputPath);
+  // Ensure it starts with the project root
+  if (!resolved.startsWith(PROJECT_ROOT)) {
+    throw new Error('Path is outside the project directory.');
+  }
+  return resolved;
+}
+
+/**
+ * Execute a shell command securely.
+ * Only commands from the whitelist are allowed.
+ */
+function executeShell(commandString) {
+  // Split command into parts (first word is the command, rest are arguments)
+  const parts = commandString.trim().split(/\s+/);
+  if (parts.length === 0) throw new Error('Empty command.');
+
+  const cmd = parts[0];
+  if (!ALLOWED_COMMANDS.has(cmd)) {
+    throw new Error(`Command "${cmd}" is not allowed.`);
+  }
+
+  const args = parts.slice(1);
+
+  try {
+    const output = execFileSync(cmd, args, {
+      cwd: PROJECT_ROOT,
+      encoding: 'utf-8',
+      timeout: 30000, // 30 seconds
+      maxBuffer: MAX_OUTPUT_SIZE,
+      stdio: 'pipe'
+    });
+    return output.trim() || 'Command executed successfully with no output.';
+  } catch (err) {
+    // If command fails, return the error message (safe to show to AI)
+    if (err.stderr) {
+      return `Error: ${err.stderr.trim()}`;
+    }
+    throw new Error(`Command execution failed: ${err.message}`);
+  }
+}
+
+/**
+ * Read a file securely, ensuring it's within the project root.
+ */
+function readFile(filePath) {
+  const safePath = sanitizePath(filePath);
   try {
-    if (toolName === 'execute_shell') {
-      const output = execSync(input.command, { encoding: 'utf-8', stdio: 'pipe' });
-      return output.trim() || 'Command executed successfully with no output.';
-    } 
-    
-    if (toolName === 'read_file') {
-      return fs.readFileSync(input.path, 'utf-8');
+    const stats = fs.statSync(safePath);
+    if (!stats.isFile()) throw new Error('Path is not a file.');
+    if (stats.size > MAX_OUTPUT_SIZE) {
+      // Read only first 1 MB
+      const buffer = Buffer.alloc(MAX_OUTPUT_SIZE);
+      const fd = fs.openSync(safePath, 'r');
+      fs.readSync(fd, buffer, 0, MAX_OUTPUT_SIZE, 0);
+      fs.closeSync(fd);
+      return buffer.toString('utf-8') + '\n... (file truncated)';
     }
+    return fs.readFileSync(safePath, 'utf-8');
+  } catch (err) {
+    throw new Error(`Failed to read file: ${err.message}`);
+  }
+}
 
-    throw new Error(`Tool ${toolName} is not supported locally.`);
+/**
+ * Write content to a file securely (optional, but useful for agent).
+ * Ensure file is within project root.
+ */
+function writeFile(filePath, content) {
+  const safePath = sanitizePath(filePath);
+  try {
+    // Ensure directory exists
+    const dir = path.dirname(safePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(safePath, content, 'utf-8');
+    return `File written successfully: ${filePath}`;
+  } catch (err) {
+    throw new Error(`Failed to write file: ${err.message}`);
+  }
+}
+
+/**
+ * Main tool dispatcher.
+ * Returns the result as a string (to be sent back to the AI).
+ */
+function executeTool(toolName, input) {
+  try {
+    switch (toolName) {
+      case 'execute_shell':
+        return executeShell(input.command);
+      case 'read_file':
+        return readFile(input.path);
+      case 'write_file':
+        return writeFile(input.path, input.content);
+      default:
+        throw new Error(`Tool "${toolName}" is not supported.`);
+    }
   } catch (error) {
-    return `Error executing tool: ${error.message}`;
+    // Return a generic error message to the AI (don't leak internal details)
+    return `Tool execution failed: ${error.message}`;
   }
 }