markov-cli 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markov-cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "LivingCloud's CLI AI Agent",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
     ".env.example"
   ],
   "dependencies": {
+    "boxen": "^8.0.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dotenv": "^16.4.5",

package/src/auth.js

@@ -17,6 +17,12 @@ export function saveToken(token) {
   writeFileSync(TOKEN_PATH, token, 'utf-8');
 }
 
+export function clearToken() {
+  if (existsSync(TOKEN_PATH)) {
+    writeFileSync(TOKEN_PATH, '', 'utf-8');
+  }
+}
+
 export async function login(email, password) {
   const res = await fetch(`${API_URL}/auth/login`, {
     method: 'POST',

package/src/files.js

@@ -76,9 +76,7 @@ export function resolveFileRefs(input, cwd = process.cwd()) {
 
   const contextBlock = blocks.length > 0
     ? `The user referenced the following file(s) as context:\n\n${blocks.join('\n\n')}\n\n` +
-      `If you need to edit a file, output the complete new file content in a fenced code block tagged with the EXACT filename, like:\n` +
-      `${loaded.map(f => `\`\`\`${f}\n// full new content\n\`\`\``).join('\n')}\n\n` +
-      `IMPORTANT: Use the exact filename shown above as the code block tag, not the language name.\n\n`
+      `ATTACHED FILES RULE: The user attached the file(s) above. If they ask you to edit, add, fix, or create anything in these files, you MUST use the write_file or search_replace tool — do not output the new or modified file content in your reply (no code blocks with file content). Use the exact paths shown above (e.g. ${loaded[0] ?? 'path'}).\n\n`
     : '';
 
   return { content: contextBlock + input, loaded, failed };

package/src/interactive.js

@@ -1,265 +1,18 @@
 import chalk from 'chalk';
+import boxen from 'boxen';
 import gradient from 'gradient-string';
 import { homedir } from 'os';
-import { resolve, relative, isAbsolute } from 'path';
-import { mkdirSync, rmSync, writeFileSync, unlinkSync, existsSync } from 'fs';
-import { join } from 'path';
+import { resolve } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
 import { printLogo } from './ui/logo.js';
-import { streamChat, MODEL, MODELS, setModel } from './ollama.js';
+import { chatWithTools, MODEL, MODELS, setModel } from './ollama.js';
 import { resolveFileRefs } from './files.js';
-import { execCommand } from './tools.js';
-import { parseEdits, applyEdit, renderDiff } from './editor.js';
+import { execCommand, AGENT_TOOLS, runTool } from './tools.js';
 import { chatPrompt } from './input.js';
 import { getFiles, getFilesAndDirs } from './ui/picker.js';
+import { getToken, login, clearToken } from './auth.js';
 
-const markovGradient = gradient(['#6366f1', '#a855f7', '#ec4899']);
-
-/** If path is absolute and under cwd, return relative path; otherwise return as-is. */
-function toRelativePath(p) {
-  const cwd = process.cwd();
-  if (!isAbsolute(p)) return p;
-  const rel = relative(cwd, p);
-  if (!rel.startsWith('..') && !isAbsolute(rel)) return rel;
-  return p;
-}
-
-/** Extract every !!run: command from a model response. */
-function parseRunCommands(text) {
-  const commands = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^!!run:\s*(.+)$/);
-    if (match) commands.push(match[1].trim());
-  }
-  return commands;
-}
-
-/** Extract every !!mkdir: path from a model response. */
-function parseMkdirCommands(text) {
-  const paths = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^!!mkdir:\s*(.+)$/);
-    if (match) paths.push(match[1].trim());
-  }
-  return paths;
-}
-
-/** Extract every !!rmdir: path from a model response. */
-function parseRmdirCommands(text) {
-  const paths = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^!!rmdir:\s*(.+)$/);
-    if (match) paths.push(match[1].trim());
-  }
-  return paths;
-}
-
-/** Extract every !!touch: path from a model response. */
-function parseTouchCommands(text) {
-  const paths = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^!!touch:\s*(.+)$/);
-    if (match) paths.push(match[1].trim());
-  }
-  return paths;
-}
-
-/** Extract every !!delete: path from a model response. */
-function parseDeleteCommands(text) {
-  const paths = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^!!delete:\s*(.+)$/);
-    if (match) paths.push(match[1].trim());
-  }
-  return paths;
-}
-
-/** Extract every !!write: path and its following fenced code block from a model response. */
-function parseWriteCommands(text) {
-  const edits = [];
-  const lines = text.split('\n');
-  let i = 0;
-  const blockRegex = /```(?:[\w./\-]*)\n([\s\S]*?)```/;
-  while (i < lines.length) {
-    const line = lines[i];
-    const writeMatch = line.match(/^!!write:\s*(.+)$/);
-    if (writeMatch) {
-      const filepath = writeMatch[1].trim();
-      if (filepath) {
-        const rest = lines.slice(i + 1).join('\n');
-        const blockMatch = rest.match(blockRegex);
-        if (blockMatch) {
-          edits.push({ filepath, content: blockMatch[1] });
-          const blockText = blockMatch[0];
-          const beforeBlock = rest.substring(0, rest.indexOf(blockText));
-          const linesBeforeBlock = beforeBlock.split('\n').length;
-          const linesInBlock = blockText.split('\n').length;
-          i += 1 + linesBeforeBlock + linesInBlock;
-          continue;
-        }
-      }
-    }
-    i++;
-  }
-  return edits;
-}
-
-/**
- * Parse and apply all file operations from a model reply.
- * Shows diffs/confirmations for each op. Returns updated allFiles list.
- * options.autoConfirm: if true, skip y/n prompts and apply all ops.
- */
-async function handleFileOps(reply, loadedFiles, options = {}) {
-  const autoConfirm = options.autoConfirm === true;
-  let allFiles = getFilesAndDirs();
-
-  // Create folders first (so !!run: cd <folder> can succeed later)
-  for (const folderPath of parseMkdirCommands(reply)) {
-    const path = toRelativePath(folderPath);
-    process.stdout.write(chalk.dim(`  mkdir: ${path} — `));
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Create folder ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      try {
-        mkdirSync(resolve(process.cwd(), path), { recursive: true });
-        allFiles = getFilesAndDirs();
-        console.log(chalk.green(`✓ created ${path}\n`));
-      } catch (err) {
-        console.log(chalk.red(`✗ could not create ${path}: ${err.message}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Create empty files
-  for (const filePath of parseTouchCommands(reply)) {
-    const path = toRelativePath(filePath);
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Create file ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      try {
-        const abs = resolve(process.cwd(), path);
-        const parentDir = abs.split('/').slice(0, -1).join('/');
-        mkdirSync(parentDir, { recursive: true });
-        writeFileSync(abs, '', { flag: 'wx' });
-        allFiles = getFilesAndDirs();
-        console.log(chalk.green(`✓ created ${path}\n`));
-      } catch (err) {
-        console.log(chalk.red(`✗ could not create ${path}: ${err.message}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Write files via !!write: path + fenced block
-  for (const { filepath, content } of parseWriteCommands(reply)) {
-    const path = toRelativePath(filepath);
-    renderDiff(path, content);
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Write ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      try {
-        applyEdit(path, content);
-        allFiles = getFilesAndDirs();
-        console.log(chalk.green(`✓ wrote ${path}\n`));
-      } catch (err) {
-        console.log(chalk.red(`✗ could not write ${path}: ${err.message}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Write / edit files (fenced blocks with path/language or single attached file)
-  const edits = parseEdits(reply, loadedFiles);
-  for (const { filepath, content } of edits) {
-    const path = toRelativePath(filepath);
-    renderDiff(path, content);
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Write ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      try {
-        applyEdit(path, content);
-        allFiles = getFilesAndDirs();
-        console.log(chalk.green(`✓ wrote ${path}\n`));
-      } catch (err) {
-        console.log(chalk.red(`✗ could not write ${path}: ${err.message}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Run terminal commands (after folders/files exist, so cd works)
-  for (const cmd of parseRunCommands(reply)) {
-    const ok = autoConfirm ? true : await confirm(chalk.bold(`Run: ${chalk.cyan(cmd)}? [y/N] `));
-    if (ok) {
-      // cd must be handled in-process — child processes can't change the parent's cwd
-      const cdMatch = cmd.match(/^cd\s+(.+)$/);
-      if (cdMatch) {
-        const target = resolve(process.cwd(), cdMatch[1].trim().replace(/^~/, homedir()));
-        try {
-          process.chdir(target);
-          allFiles = getFilesAndDirs();
-          console.log(chalk.dim(`  📁 ${process.cwd()}\n`));
-        } catch (err) {
-          console.log(chalk.red(`  no such directory: ${target}\n`));
-        }
-        continue;
-      }
-      process.stdout.write(chalk.dim(`  running: ${cmd}\n`));
-      const { stdout, stderr, exitCode } = await execCommand(cmd);
-      const output = [stdout, stderr].filter(Boolean).join('\n').trim();
-      console.log(output ? chalk.dim(output) + '\n' : chalk.dim(`  (exit ${exitCode})\n`));
-      allFiles = getFilesAndDirs();
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Remove directories
-  for (const dirPath of parseRmdirCommands(reply)) {
-    const path = toRelativePath(dirPath);
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Remove directory ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      const abs = resolve(process.cwd(), path);
-      if (existsSync(abs)) {
-        try {
-          rmSync(abs, { recursive: true, force: true });
-          allFiles = getFilesAndDirs();
-          console.log(chalk.green(`✓ removed ${path}\n`));
-        } catch (err) {
-          console.log(chalk.red(`✗ could not remove ${path}: ${err.message}\n`));
-        }
-      } else {
-        console.log(chalk.yellow(`⚠  not found: ${path}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  // Delete files
-  for (const filePath of parseDeleteCommands(reply)) {
-    const path = toRelativePath(filePath);
-    const confirmed = autoConfirm ? true : await confirm(chalk.bold(`Delete ${chalk.cyan(path)}? [y/N] `));
-    if (confirmed) {
-      const abs = resolve(process.cwd(), path);
-      if (existsSync(abs)) {
-        try {
-          unlinkSync(abs);
-          allFiles = getFilesAndDirs();
-          console.log(chalk.green(`✓ deleted ${path}\n`));
-        } catch (err) {
-          console.log(chalk.red(`✗ could not delete ${path}: ${err.message}\n`));
-        }
-      } else {
-        console.log(chalk.yellow(`⚠  not found: ${path}\n`));
-      }
-    } else {
-      console.log(chalk.dim('skipped\n'));
-    }
-  }
-
-  return allFiles;
-}
+const agentGradient = gradient(['#22c55e', '#16a34a', '#4ade80']);
 
 /** Arrow-key selector. Returns the chosen string or null if cancelled. */
 function selectFrom(options, label) {
@@ -376,7 +129,6 @@ function promptSecret(label) {
   });
 }
 
-const VIEWPORT_LINES = 5;
 const TERM_WIDTH = 80;
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 const visLen = (s) => s.replace(ANSI_RE, '').length;
@@ -402,144 +154,292 @@ function wrapText(text, width) {
   }).join('\n');
 }
 
-/** Count the number of terminal rows a list of lines occupies, accounting for wrapping. */
-function countRows(lines, w) {
-  return lines.reduce((sum, l) => sum + Math.max(1, Math.ceil(visLen(l) / w)), 0);
+/** Parse fenced code blocks (```lang\n...\n```) and render them with boxen. Non-code segments are wrapped. */
+function formatResponseWithCodeBlocks(text, width) {
+  if (!text || typeof text !== 'string') return '';
+  const re = /```(\w*)\n([\s\S]*?)```/g;
+  const parts = [];
+  let lastIndex = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m.index > lastIndex) {
+      const textSegment = text.slice(lastIndex, m.index);
+      if (textSegment) parts.push({ type: 'text', content: textSegment });
+    }
+    parts.push({ type: 'code', lang: m[1], content: m[2].trim() });
+    lastIndex = re.lastIndex;
+  }
+  if (lastIndex < text.length) {
+    const textSegment = text.slice(lastIndex);
+    if (textSegment) parts.push({ type: 'text', content: textSegment });
+  }
+  if (parts.length === 0) return wrapText(text, width);
+  return parts.map((p) => {
+    if (p.type === 'text') return wrapText(p.content, width);
+    const title = p.lang ? p.lang : 'code';
+    return boxen(p.content, {
+      borderColor: 'cyan',
+      borderStyle: 'round',
+      title,
+      padding: 1,
+    });
+  }).join('\n\n');
 }
 
-/**
- * Stream a chat response with a live 5-line viewport.
- * While streaming, only the last VIEWPORT_LINES lines are shown in-place.
- * After streaming finishes, the viewport is replaced with the full response.
- * Returns the full reply string.
- */
-function buildSystemMessage() {
+/** Shared system message base: Markov intro, cwd, file list (no !!run instructions). */
+function getSystemMessageBase() {
   const files = getFiles();
   const fileList = files.length > 0 ? `\nFiles in working directory:\n${files.map(f => `  ${f}`).join('\n')}\n` : '';
-  const fileOpsInstructions =
-    `\nFILE OPERATIONS — use these exact syntaxes when needed:\n` +
-    `- Always use RELATIVE paths (e.g. path/to/file or markov/next-app/README.md), never absolute paths like /Users/...\n` +
-    `- Run a terminal command: output exactly on its own line: !!run: <command>\n` +
-    `- Write or edit a file: output exactly on its own line !!write: path/to/file, then a fenced code block with the full file content.\n` +
-    `- Create an empty file: output exactly on its own line: !!touch: path/to/file\n` +
-    `- Create a folder: output exactly on its own line: !!mkdir: path/to/folder\n` +
-    `- Remove a folder: output exactly on its own line: !!rmdir: path/to/folder\n` +
-    `- Delete a file: output exactly on its own line: !!delete: path/to/file\n` +
-    `- You may combine multiple operations in one response.\n` +
-    `- NEVER put commands in fenced code blocks — always use !!run: syntax for commands.\n` +
-    `- NEVER use && inside !!run: — use one !!run: per command. For "cd then do X", output !!run: cd <path> on one line, then !!run: <command> on the next (cd changes the working directory for all following commands).\n` +
-    `\nSETUP NEXT.JS APP (or any new project in a subfolder):\n` +
-    `1. Create the folder first: !!mkdir: next-app (or the requested name).\n` +
-    `2. Change into it on its own line: !!run: cd next-app (nothing after the path).\n` +
-    `3. Run each following command on its own !!run: line: e.g. !!run: npx create-next-app@latest . --yes, then !!run: git init, !!run: git add ., !!run: git commit -m "Initial commit".\n` +
-    `\nSETUP LARAVEL API (output exactly this):\n` +
-    `!!mkdir: laravel-api then !!run: cd laravel-api then !!run: composer create-project --prefer-dist laravel/laravel . then !!run: php artisan serve. One per line; nothing after the dot in composer; no composer run dev or dev-server. No custom routes.\n` +
-    `\nSETUP ROUTES (API only — use when user asks to add routes, /health, /users, or API endpoints):\n` +
-    `Only after the Laravel app exists. Add in routes/api.php only (not web.php): GET /api/health returning response()->json(['status' => 'ok']), and /api/users as a resource (index, show, store, update, destroy) using User model and a controller. Register api in bootstrap/app.php if needed. Use !!write: for routes/api.php and the controller; prefix with laravel-api/ if cwd is parent. Do not use routes/web.php.\n`;
-  return { role: 'system', content: `You are Markov, an AI coding assistant.\nWorking directory: ${process.cwd()}\n${fileList}${fileOpsInstructions}` };
+  return `You are Markov, an AI coding assistant.\nWorking directory: ${process.cwd()}\n${fileList}`;
 }
 
-async function streamWithViewport(chatMessages, signal) {
-  // Re-resolve @file refs fresh on every request so the model always sees the latest file contents.
-  const resolvedMessages = chatMessages.map(msg => {
-    if (msg.role !== 'user') return msg;
-    const { content } = resolveFileRefs(msg.content);
-    return { ...msg, content };
-  });
-
-  const DOTS = ['.', '..', '...'];
-  let dotIdx = 0;
-  let firstToken = true;
-  let fullText = '';
-  let viewportRows = 0; // actual terminal rows currently rendered in the viewport
+/** System message for agent mode: tool-only instructions (no !!run / !!write). */
+function buildAgentSystemMessage() {
+  const toolInstructions =
+    `\nTOOL MODE — you have tools; use them. \n` +
+    `- run_terminal_command: run shell commands (npm install, npx create-next-app, etc.). One command per call.\n` +
+    `- create_folder: create directories.\n` +
+    `- read_file: read file contents before editing.\n` +
+    `- write_file: create or overwrite a file with full content.\n` +
+    `- search_replace: replace first occurrence of text in a file.\n` +
+    `- delete_file: delete a file.\n` +
+    `- list_dir: list directory contents (path optional, defaults to current dir).\n` +
+    `When the user asks to run commands, create/edit/delete files, scaffold projects, or to "plan" or "start" an app (e.g. npm run dev), call these tools — do not only list commands or describe steps in your reply. Execute with tool calls.\n` +
+    `When the user has ATTACHED FILES (FILE: path ... in the message), any edit, add, or fix they ask for in those files MUST be done with write_file or search_replace — never by pasting the modified file content in your reply.\n` +
+    `Use RELATIVE paths.\n`;
+  return { role: 'system', content: getSystemMessageBase() + toolInstructions };
+}
 
-  process.stdout.write(chalk.dim('\nMarkov › '));
-  const spinner = setInterval(() => {
-    process.stdout.write('\r' + chalk.dim('Markov › ') + markovGradient(DOTS[dotIdx % DOTS.length]) + '   ');
-    dotIdx++;
-  }, 400);
+const AGENT_LOOP_MAX_ITERATIONS = 20;
+
+/** Preview of a file edit for confirmation (write_file / search_replace) */
+function formatFileEditPreview(name, args) {
+  const path = args?.path ?? '(no path)';
+  if (name === 'search_replace') {
+    const oldStr = String(args?.old_string ?? '');
+    const newStr = String(args?.new_string ?? '');
+    const max = 120;
+    const oldPreview = oldStr.length > max ? oldStr.slice(0, max) + '…' : oldStr;
+    const newPreview = newStr.length > max ? newStr.slice(0, max) + '…' : newStr;
+    return (
+      chalk.cyan(path) + '\n' +
+      chalk.red('  - ' + (oldPreview || '(empty)').replace(/\n/g, '\n    ')) + '\n' +
+      chalk.green('  + ' + (newPreview || '(empty)').replace(/\n/g, '\n    '))
+    );
+  }
+  if (name === 'write_file') {
+    const content = String(args?.content ?? '');
+    const lines = content.split('\n');
+    const previewLines = lines.slice(0, 25);
+    const more = lines.length > 25 ? chalk.dim(`  ... ${lines.length - 25} more lines`) : '';
+    return chalk.cyan(path) + '\n' + previewLines.map(l => '  ' + l).join('\n') + (more ? '\n' + more : '');
+  }
+  return path;
+}
 
-  const onCancel = (data) => { if (data.toString() === '\x11') signal.abort(); };
-  process.stdin.setRawMode(true);
-  process.stdin.resume();
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', onCancel);
+/** One-line summary of tool args for display */
+function formatToolCallSummary(name, args) {
+  const a = args ?? {};
+  if (name === 'run_terminal_command') return (a.command ?? '').trim() || '(empty)';
+  if (name === 'write_file') return a.path ?? '(no path)';
+  if (name === 'search_replace') return (a.path ?? '') + (a.old_string ? ` "${String(a.old_string).slice(0, 30)}…"` : '');
+  if (name === 'read_file' || name === 'delete_file') return a.path ?? '(no path)';
+  if (name === 'create_folder') return a.path ?? '(no path)';
+  if (name === 'list_dir') return (a.path ?? '.') || '.';
+  return JSON.stringify(a).slice(0, 50);
+}
 
+/** One-line summary of tool result for display */
+function formatToolResultSummary(name, resultJson) {
+  let obj;
   try {
-    const reply = await streamChat([buildSystemMessage(), ...resolvedMessages], (token) => {
-      if (firstToken) {
-        clearInterval(spinner);
-        firstToken = false;
-        process.stdout.write('\r\x1b[0J' + chalk.dim('Markov ›\n\n'));
-      }
+    obj = typeof resultJson === 'string' ? JSON.parse(resultJson) : resultJson;
+  } catch {
+    return resultJson?.slice(0, 60) ?? '—';
+  }
+  if (obj.error) return chalk.red('✗ ' + obj.error);
+  if (obj.declined) return chalk.yellow('✗ declined');
+  if (name === 'run_terminal_command') {
+    const code = obj.exitCode ?? obj.exit_code;
+    if (code === 0) return chalk.green('✓ exit 0') + (obj.stdout ? chalk.dim('  ' + String(obj.stdout).trim().slice(0, 80).replace(/\n/g, ' ')) : '');
+    return chalk.red(`✗ exit ${code}`) + (obj.stderr ? chalk.dim('  ' + String(obj.stderr).trim().slice(0, 80)) : '');
+  }
+  if (name === 'write_file' || name === 'search_replace' || name === 'delete_file' || name === 'create_folder') {
+    return obj.success !== false ? chalk.green('✓ ' + (obj.path ? obj.path : 'ok')) : chalk.red('✗ ' + (obj.error || 'failed'));
+  }
+  if (name === 'read_file') return obj.content != null ? chalk.green('✓ ' + (obj.path ?? '') + chalk.dim(` (${String(obj.content).length} chars)`)) : chalk.red('✗ ' + (obj.error || ''));
+  if (name === 'list_dir') return obj.entries ? chalk.green('✓ ' + (obj.entries.length ?? 0) + ' entries') : chalk.red('✗ ' + (obj.error || ''));
+  return chalk.dim(JSON.stringify(obj).slice(0, 60));
+}
 
-      fullText += token;
+/**
+ * Run the agent loop: call chatWithTools, run any tool_calls locally, append results, repeat until the model returns a final response.
+ * For write_file and search_replace, confirmFileEdit is called first; if it returns false, the change is skipped and the model is told the user declined.
+ * @param {Array<{ role: string; content?: string; tool_calls?: unknown[]; tool_name?: string }>} messages - Full message list (system + conversation)
+ * @param {{ signal?: AbortSignal; cwd?: string; confirmFn?: (command: string) => Promise<boolean>; confirmFileEdit?: (name: string, args: object) => Promise<boolean>; onBeforeToolRun?: () => void; onToolCall?: (name: string, args: object) => void; onToolResult?: (name: string, result: string) => void }} opts
+ * @returns {Promise<{ content: string; finalMessage: object } | null>} Final assistant content and message, or null if cancelled/error
+ */
+async function runAgentLoop(messages, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const confirmFn = opts.confirmFn;
+  const confirmFileEdit = opts.confirmFileEdit;
+  const onBeforeToolRun = opts.onBeforeToolRun;
+  const onToolCall = opts.onToolCall;
+  const onToolResult = opts.onToolResult;
+  let iteration = 0;
+
+  while (iteration < AGENT_LOOP_MAX_ITERATIONS) {
+    iteration += 1;
+    const data = await chatWithTools(messages, AGENT_TOOLS, MODEL, opts.signal ?? null);
+
+    const message = data?.message;
+    if (!message) {
+      return { content: '', finalMessage: { role: 'assistant', content: '' } };
+    }
+
+    const toolCalls = message.tool_calls;
+    if (!toolCalls || toolCalls.length === 0) {
+      return { content: message.content ?? '', finalMessage: message };
+    }
 
-      // Build the viewport: last VIEWPORT_LINES lines of buffered text.
-      const w = process.stdout.columns || TERM_WIDTH;
-      const displayWidth = Math.min(w, TERM_WIDTH);
-      const lines = wrapText(fullText, displayWidth).split('\n');
-      const viewLines = lines;
-      const rendered = viewLines.join('\n');
+    // Append assistant message with tool_calls
+    messages.push({
+      role: 'assistant',
+      content: message.content ?? '',
+      tool_calls: toolCalls,
+    });
 
-      // Count actual terminal rows rendered (accounts for line wrapping).
-      const newRows = countRows(viewLines, w) - 1;
+    onBeforeToolRun?.();
+
+    for (const tc of toolCalls) {
+      const name = tc?.function?.name;
+      const rawArgs = tc?.function?.arguments;
+      let args = rawArgs;
+      if (typeof rawArgs === 'string') {
+        try {
+          args = JSON.parse(rawArgs);
+        } catch {
+          messages.push({
+            role: 'tool',
+            tool_name: name ?? 'unknown',
+            content: JSON.stringify({ error: 'Invalid JSON in arguments' }),
+          });
+          if (onToolCall) onToolCall(name ?? 'unknown', {});
+          if (onToolResult) onToolResult(name ?? 'unknown', JSON.stringify({ error: 'Invalid JSON in arguments' }));
+          continue;
+        }
+      }
 
-      // Move cursor up to top of current viewport, clear down, rewrite.
-      if (viewportRows > 0) {
-        process.stdout.write(`\x1b[${viewportRows}A\r\x1b[0J`);
+      if (onToolCall) onToolCall(name ?? 'unknown', args ?? {});
+
+      const isFileEdit = name === 'write_file' || name === 'search_replace';
+      let result;
+      if (isFileEdit && confirmFileEdit) {
+        const ok = await confirmFileEdit(name, args ?? {});
+        if (!ok) {
+          result = JSON.stringify({ declined: true, message: 'User declined the change' });
+          if (onToolResult) onToolResult(name ?? 'unknown', result);
+          messages.push({
+            role: 'tool',
+            tool_name: name ?? 'unknown',
+            content: result,
+          });
+          continue;
+        }
       }
-      process.stdout.write(rendered);
-      viewportRows = newRows;
-    }, undefined, signal);
-
-    process.stdin.removeListener('data', onCancel);
-    process.stdin.setRawMode(false);
-    process.stdin.pause();
-    clearInterval(spinner);
-
-    if (signal.aborted) {
-      if (viewportRows > 0) process.stdout.write(`\x1b[${viewportRows}A\r\x1b[0J`);
-      console.log(chalk.dim('(cancelled)\n'));
-      return null;
-    }
 
-    // Replace viewport with the full response.
-    if (viewportRows > 0) process.stdout.write(`\x1b[${viewportRows}A\r\x1b[0J`);
-    const finalWidth = Math.min(process.stdout.columns || TERM_WIDTH, TERM_WIDTH);
-    process.stdout.write(wrapText(fullText, finalWidth) + '\n\n');
-
-    return reply;
-  } catch (err) {
-    clearInterval(spinner);
-    process.stdin.removeListener('data', onCancel);
-    process.stdin.setRawMode(false);
-    process.stdin.pause();
-    if (!signal.aborted) throw err;
-    return null;
+      result = await runTool(name, args ?? {}, { cwd, confirmFn });
+      if (onToolResult) onToolResult(name ?? 'unknown', typeof result === 'string' ? result : JSON.stringify(result));
+      messages.push({
+        role: 'tool',
+        tool_name: name ?? 'unknown',
+        content: typeof result === 'string' ? result : JSON.stringify(result),
+      });
+    }
   }
+
+  return {
+    content: '(agent loop reached max iterations)',
+    finalMessage: { role: 'assistant', content: '(max iterations)' },
+  };
 }
 
 const HELP_TEXT =
   '\n' +
   chalk.bold('Commands:\n') +
   chalk.cyan('  /help') + chalk.dim('                       show this help\n') +
-  chalk.cyan('  /plan <message>') + chalk.dim('             ask AI to create a plan (no files written)\n') +
-  chalk.cyan('  /build') + chalk.dim('                      execute the stored plan\n') +
+  chalk.cyan('  /agent') + chalk.dim(' [prompt]             run with tools (run commands, create folders)\n') +
+  chalk.cyan('  /setup-nextjs') + chalk.dim('               scaffold a Next.js app\n') +
+  chalk.cyan('  /setup-laravel') + chalk.dim('              scaffold a Laravel API\n') +
   chalk.cyan('  /models') + chalk.dim('                     switch the active AI model\n') +
   chalk.cyan('  /cd [path]') + chalk.dim('                  change working directory\n') +
-  chalk.dim('\nNormal chat: plan then build (no y/n). Tips: ') + chalk.cyan('@filename') + chalk.dim(' to attach a file · ctrl+q to cancel\n');
+  chalk.cyan('  /login') + chalk.dim('                      authenticate with email & password\n') +
+  chalk.cyan('  /logout') + chalk.dim('                     clear saved auth token\n') +
+  chalk.dim('\nType a message · ') + chalk.cyan('@filename') + chalk.dim(' to attach · ctrl+q to cancel\n');
+
+/**
+ * Run a list of setup steps (mkdir / cd / run / write) in sequence.
+ * Returns true if all steps succeeded, false if any failed.
+ */
+async function runSetupSteps(steps) {
+  for (const step of steps) {
+    if (step.type === 'mkdir') {
+      process.stdout.write(chalk.dim(`  mkdir: ${step.path}\n`));
+      try {
+        mkdirSync(resolve(process.cwd(), step.path), { recursive: true });
+        console.log(chalk.green(`  ✓ created ${step.path}\n`));
+      } catch (err) {
+        console.log(chalk.red(`  ✗ ${err.message}\n`));
+        return false;
+      }
+    } else if (step.type === 'cd') {
+      try {
+        process.chdir(resolve(process.cwd(), step.path));
+        console.log(chalk.dim(`  📁 ${process.cwd()}\n`));
+      } catch (err) {
+        console.log(chalk.red(`  ✗ no such directory: ${step.path}\n`));
+        return false;
+      }
+    } else if (step.type === 'run') {
+      process.stdout.write(chalk.dim(`  running: ${step.cmd}\n`));
+      const { stdout, stderr, exitCode } = await execCommand(step.cmd);
+      const output = [stdout, stderr].filter(Boolean).join('\n').trim();
+      if (output) console.log(chalk.dim(output));
+      if (exitCode !== 0) {
+        console.log(chalk.red(`  ✗ command failed (exit ${exitCode})\n`));
+        return false;
+      }
+      console.log(chalk.green(`  ✓ done\n`));
+    } else if (step.type === 'write') {
+      process.stdout.write(chalk.dim(`  write: ${step.path}\n`));
+      try {
+        const abs = resolve(process.cwd(), step.path);
+        const dir = abs.split('/').slice(0, -1).join('/');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(abs, step.content);
+        console.log(chalk.green(`  ✓ wrote ${step.path}\n`));
+      } catch (err) {
+        console.log(chalk.red(`  ✗ ${err.message}\n`));
+        return false;
+      }
+    }
+  }
+  return true;
+}
 
 export async function startInteractive() {
   printLogo();
 
   let allFiles = getFilesAndDirs();
   const chatMessages = [];
-  let currentPlan = null; // { text: string } | null
 
   console.log(chalk.dim(`Chat with Markov (${MODEL}).`));
   console.log(HELP_TEXT);
 
+  if (!getToken()) {
+    console.log(chalk.yellow('⚠  Not logged in. Use /login to authenticate.\n'));
+  }
+
   while (true) {
     const raw = await chatPrompt(chalk.magenta('you> '), allFiles);
     if (raw === null) continue;
@@ -547,6 +447,26 @@ export async function startInteractive() {
 
     if (!trimmed) continue;
 
+    // /login — authenticate and save token
+    if (trimmed === '/login') {
+      const email    = await promptLine('Email: ');
+      const password = await promptSecret('Password: ');
+      try {
+        await login(email, password);
+        console.log(chalk.green('✓ logged in\n'));
+      } catch (err) {
+        console.log(chalk.red(`✗ ${err.message}\n`));
+      }
+      continue;
+    }
+
+    // /logout — clear saved token
+    if (trimmed === '/logout') {
+      clearToken();
+      console.log(chalk.green('✓ logged out\n'));
+      continue;
+    }
+
     // /help — list all commands
     if (trimmed === '/help') {
       console.log(HELP_TEXT);
@@ -579,110 +499,157 @@ export async function startInteractive() {
       continue;
     }
 
-    // /plan <message> — ask LLM to produce a plan as a normal chat message, store it
-    if (trimmed.startsWith('/plan ')) {
-      const planRequest = trimmed.slice(6).trim();
-      const planPrompt =
-        `Create a detailed, numbered plan for the following task:\n\n${planRequest}\n\n` +
-        `For each step, specify exactly what will happen and which syntax will be used:\n` +
-        `- Writing or editing a file → !!write: path/to/file then fenced code block\n` +
-        `- Creating an empty file   → !!touch: path/to/file\n` +
-        `- Creating a folder        → !!mkdir: path/to/folder\n` +
-        `- Removing a folder        → !!rmdir: path/to/folder\n` +
-        `- Deleting a file          → !!delete: path/to/file\n\n` +
-        `Do NOT output any actual file contents or commands yet — only the plan.`;
-      chatMessages.push({ role: 'user', content: planPrompt });
-      const abortController = new AbortController();
-      try {
-        const reply = await streamWithViewport(chatMessages, abortController.signal);
-        if (reply === null) {
-          chatMessages.pop();
-        } else {
-          chatMessages.push({ role: 'assistant', content: reply });
-          currentPlan = { text: reply };
-          console.log(chalk.green('\n✓ Plan stored. Use /build to execute it.\n'));
-        }
-      } catch (err) {
-        if (!abortController.signal.aborted) console.log(chalk.red(`\n${err.message}\n`));
-      }
+    // /setup-nextjs — scaffold a Next.js app via script
+    if (trimmed === '/setup-nextjs') {
+      const name = (await promptLine(chalk.bold('App folder name: '))).trim() || 'next-app';
+      const steps = [
+        { type: 'mkdir', path: name },
+        { type: 'cd',    path: name },
+        { type: 'run',   cmd: 'npx create-next-app@latest . --yes' },
+        { type: 'run',   cmd: 'npm install sass' },
+      ];
+      const ok = await runSetupSteps(steps);
+      allFiles = getFilesAndDirs();
+      if (ok) console.log(chalk.green(`✓ Next.js app created in ${name}.\n`));
       continue;
     }
 
-    // /build — execute the stored plan with full file ops
-    if (trimmed === '/build') {
-      if (!currentPlan) {
-        console.log(chalk.yellow('\n⚠  No plan stored. Use /plan <message> first.\n'));
+    // /setup-laravel — scaffold a Laravel API via script
+    if (trimmed === '/setup-laravel') {
+      const name = (await promptLine(chalk.bold('App folder name: '))).trim() || 'laravel-api';
+      const steps = [
+        { type: 'mkdir', path: name },
+        { type: 'cd',    path: name },
+        { type: 'run',   cmd: 'composer create-project --prefer-dist laravel/laravel .' },
+        { type: 'run',   cmd: 'php artisan serve' },
+      ];
+      const ok = await runSetupSteps(steps);
+      allFiles = getFilesAndDirs();
+      if (ok) console.log(chalk.green(`✓ Laravel API created in ${name}.\n`));
+      continue;
+    }
+
+    // /agent [prompt] — run with tools (run_terminal_command, create_folder, file tools), loop until final response
+    if (trimmed === '/agent' || trimmed.startsWith('/agent ')) {
+      const userContent = trimmed.startsWith('/agent ')
+        ? trimmed.slice(7).trim()
+        : (await promptLine(chalk.bold('Agent prompt: '))).trim();
+      if (!userContent) {
+        console.log(chalk.yellow('No prompt given.\n'));
         continue;
       }
-
-      const buildPrompt =
-        `Execute the following plan. Use !!write: path then a fenced code block for file writes, !!mkdir: for folders, !!delete: for deletions.\n\n` +
-        `Plan:\n${currentPlan.text}`;
-
-      chatMessages.push({ role: 'user', content: buildPrompt });
+      chatMessages.push({ role: 'user', content: userContent });
+      const agentMessages = [buildAgentSystemMessage(), ...chatMessages];
       const abortController = new AbortController();
+      const confirmFn = (cmd) => confirm(chalk.bold(`Run: ${cmd}? [y/N] `));
+      const confirmFileEdit = async (name, args) => {
+        console.log(chalk.dim('\n  Proposed change:\n'));
+        console.log(formatFileEditPreview(name, args));
+        console.log('');
+        return confirm(chalk.bold('Apply this change? [y/N] '));
+      };
+
+      const DOTS = ['.', '..', '...'];
+      let dotIdx = 0;
+      process.stdout.write(chalk.dim('\nAgent › '));
+      const spinner = setInterval(() => {
+        process.stdout.write('\r' + chalk.dim('Agent › ') + agentGradient(DOTS[dotIdx % DOTS.length]) + '   ');
+        dotIdx++;
+      }, 400);
+
       try {
-        const reply = await streamWithViewport(chatMessages, abortController.signal);
-        if (reply === null) {
-          chatMessages.pop();
-        } else {
-          chatMessages.push({ role: 'assistant', content: reply });
-          allFiles = await handleFileOps(reply, []);
-          currentPlan = null;
-          console.log(chalk.green('✓ Plan executed.\n'));
+        const result = await runAgentLoop(agentMessages, {
+          signal: abortController.signal,
+          cwd: process.cwd(),
+          confirmFn,
+          confirmFileEdit,
+          onBeforeToolRun: () => {
+            clearInterval(spinner);
+            process.stdout.write('\r\x1b[0J');
+          },
+          onToolCall: (name, args) => {
+            const summary = formatToolCallSummary(name, args);
+            console.log(chalk.cyan('  ▶ ') + chalk.bold(name) + chalk.dim('  ') + chalk.white(summary));
+          },
+          onToolResult: (name, resultStr) => {
+            console.log(chalk.dim('    ') + formatToolResultSummary(name, resultStr));
+          },
+        });
+        clearInterval(spinner);
+        process.stdout.write('\r\x1b[0J');
+        if (result) {
+          chatMessages.push(result.finalMessage);
+          const width = Math.min(process.stdout.columns || 80, 80);
+          process.stdout.write(formatResponseWithCodeBlocks(result.content, width) + '\n\n');
+          allFiles = getFilesAndDirs();
+          console.log(chalk.green('✓ Agent done.\n'));
         }
       } catch (err) {
-        if (!abortController.signal.aborted) console.log(chalk.red(`\n${err.message}\n`));
+        clearInterval(spinner);
+        process.stdout.write('\r\x1b[0J');
+        if (!abortController.signal?.aborted) console.log(chalk.red(`\n${err.message}\n`));
       }
       continue;
     }
 
-    // Normal chat — plan then build (two phases), apply file ops without y/n
-    const { loaded, failed } = resolveFileRefs(trimmed);
-
+    // Handle message with agent (tools)
+    const { loaded, failed, content: resolvedContent } = await resolveFileRefs(trimmed);
     if (loaded.length > 0) {
       console.log(chalk.dim(`\n📎 attached: ${loaded.map(f => chalk.cyan(`@${f}`)).join(', ')}`));
     }
     if (failed.length > 0) {
       console.log(chalk.yellow(`\n⚠  not found: ${failed.map(f => `@${f}`).join(', ')}`));
     }
+    const userContent = resolvedContent ?? trimmed;
+    chatMessages.push({ role: 'user', content: userContent });
 
-    const planPrompt =
-      `Create a detailed, numbered plan for the following task:\n\n${trimmed}\n\n` +
-      `For each step, specify exactly what will happen and which syntax will be used:\n` +
-      `- Writing or editing a file → !!write: path/to/file then fenced code block\n` +
-      `- Creating an empty file   → !!touch: path/to/file\n` +
-      `- Creating a folder        → !!mkdir: path/to/folder\n` +
-      `- Removing a folder        → !!rmdir: path/to/folder\n` +
-      `- Deleting a file          → !!delete: path/to/file\n\n` +
-      `Do NOT output any actual file contents or commands yet — only the plan.`;
-
-    chatMessages.push({ role: 'user', content: planPrompt });
+    const agentMessages = [buildAgentSystemMessage(), ...chatMessages];
     const abortController = new AbortController();
+    const confirmFn = (cmd) => confirm(chalk.bold(`Run: ${cmd}? [y/N] `));
+    const confirmFileEdit = async (name, args) => {
+      console.log(chalk.dim('\n  Proposed change:\n'));
+      console.log(formatFileEditPreview(name, args));
+      console.log('');
+      return confirm(chalk.bold('Apply this change? [y/N] '));
+    };
+    const DOTS = ['.', '..', '...'];
+    let dotIdx = 0;
+    process.stdout.write(chalk.dim('\nAgent › '));
+    const spinner = setInterval(() => {
+      process.stdout.write('\r' + chalk.dim('Agent › ') + agentGradient(DOTS[dotIdx % DOTS.length]) + '   ');
+      dotIdx++;
+    }, 400);
     try {
-      const planReply = await streamWithViewport(chatMessages, abortController.signal);
-      if (planReply === null) {
-        chatMessages.pop();
-        continue;
-      }
-      chatMessages.push({ role: 'assistant', content: planReply });
-
-      const buildPrompt =
-        `Execute the following plan. Use !!write: path then a fenced code block for file writes, !!mkdir: for folders, !!delete: for deletions.\n\n` +
-        `Plan:\n${planReply}`;
-
-      chatMessages.push({ role: 'user', content: buildPrompt });
-      const buildReply = await streamWithViewport(chatMessages, abortController.signal);
-      if (buildReply === null) {
-        chatMessages.pop(); // remove build prompt
-        continue;
+      const result = await runAgentLoop(agentMessages, {
+        signal: abortController.signal,
+        cwd: process.cwd(),
+        confirmFn,
+        confirmFileEdit,
+        onBeforeToolRun: () => {
+          clearInterval(spinner);
+          process.stdout.write('\r\x1b[0J');
+        },
+        onToolCall: (name, args) => {
+          const summary = formatToolCallSummary(name, args);
+          console.log(chalk.cyan('  ▶ ') + chalk.bold(name) + chalk.dim('  ') + chalk.white(summary));
+        },
+        onToolResult: (name, resultStr) => {
+          console.log(chalk.dim('    ') + formatToolResultSummary(name, resultStr));
+        },
+      });
+      clearInterval(spinner);
+      process.stdout.write('\r\x1b[0J');
+      if (result) {
+        chatMessages.push(result.finalMessage);
+        const width = Math.min(process.stdout.columns || 80, 80);
+        process.stdout.write(formatResponseWithCodeBlocks(result.content, width) + '\n\n');
+        allFiles = getFilesAndDirs();
+        console.log(chalk.green('✓ Agent done.\n'));
       }
-      chatMessages.push({ role: 'assistant', content: buildReply });
-      allFiles = await handleFileOps(buildReply, loaded, { autoConfirm: true });
     } catch (err) {
-      if (!abortController.signal.aborted) {
-        console.log(chalk.red(`\n${err.message}\n`));
-      }
+      clearInterval(spinner);
+      process.stdout.write('\r\x1b[0J');
+      if (!abortController.signal?.aborted) console.log(chalk.red(`\n${err.message}\n`));
     }
   }
 }

package/src/tools.js

@@ -1,7 +1,7 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import { mkdirSync } from 'fs';
-import { resolve } from 'path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, readdirSync, statSync } from 'fs';
+import { resolve, dirname } from 'path';
 
 const execAsync = promisify(exec);
 
@@ -47,6 +47,130 @@ export const CREATE_FOLDER_TOOL = {
   },
 };
 
+/** Ollama-format tool definition for reading a file */
+export const READ_FILE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'read_file',
+    description: 'Read the contents of a file. Use before editing to see current content. Path is relative to the current working directory.',
+    parameters: {
+      type: 'object',
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path to the file (e.g. "src/index.js").',
+        },
+      },
+    },
+  },
+};
+
+/** Ollama-format tool definition for writing or overwriting a file */
+export const WRITE_FILE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'write_file',
+    description: 'Create or overwrite a file with the given content. Creates parent directories if needed. Use for new files or when replacing the entire file.',
+    parameters: {
+      type: 'object',
+      required: ['path', 'content'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path to the file (e.g. "src/App.js").',
+        },
+        content: {
+          type: 'string',
+          description: 'Full file content to write.',
+        },
+      },
+    },
+  },
+};
+
+/** Ollama-format tool definition for search-and-replace in a file */
+export const SEARCH_REPLACE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'search_replace',
+    description: 'Replace the first occurrence of old_string with new_string in a file. Use for small, targeted edits. old_string must match exactly (including whitespace).',
+    parameters: {
+      type: 'object',
+      required: ['path', 'old_string', 'new_string'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path to the file.',
+        },
+        old_string: {
+          type: 'string',
+          description: 'Exact substring to find and replace (first occurrence only).',
+        },
+        new_string: {
+          type: 'string',
+          description: 'Replacement text.',
+        },
+      },
+    },
+  },
+};
+
+/** Ollama-format tool definition for deleting a file */
+export const DELETE_FILE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'delete_file',
+    description: 'Delete a file. Does not remove directories.',
+    parameters: {
+      type: 'object',
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path to the file to delete.',
+        },
+      },
+    },
+  },
+};
+
+/** Ollama-format tool definition for listing directory contents */
+export const LIST_DIR_TOOL = {
+  type: 'function',
+  function: {
+    name: 'list_dir',
+    description: 'List files and folders in a directory. Use to discover paths before reading or editing.',
+    parameters: {
+      type: 'object',
+      required: [],
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Relative path to the directory (default "." for current directory).',
+        },
+      },
+    },
+  },
+};
+
+/** Tools array for agent loop (chatWithTools). */
+export const AGENT_TOOLS = [
+  RUN_TERMINAL_COMMAND_TOOL,
+  CREATE_FOLDER_TOOL,
+  READ_FILE_TOOL,
+  WRITE_FILE_TOOL,
+  SEARCH_REPLACE_TOOL,
+  DELETE_FILE_TOOL,
+  LIST_DIR_TOOL,
+];
+
+function getPath(args, opts) {
+  const raw = typeof args.path === 'string' ? args.path : String(args?.path ?? '');
+  const cwd = opts.cwd ?? process.cwd();
+  return { path: raw.trim(), cwd, absPath: resolve(cwd, raw.trim()) };
+}
+
 const TOOLS_MAP = {
   create_folder: async (args, opts = {}) => {
     const folderPath = typeof args.path === 'string' ? args.path : String(args?.path ?? '');
@@ -62,6 +186,77 @@ const TOOLS_MAP = {
       return { success: false, error: err.message };
     }
   },
+  read_file: async (args, opts = {}) => {
+    const { path: relPath, absPath } = getPath(args, opts);
+    if (!relPath) return { error: 'Error: empty path' };
+    try {
+      if (!existsSync(absPath)) return { error: 'File not found' };
+      const stat = statSync(absPath);
+      if (!stat.isFile()) return { error: 'Not a file (is directory)' };
+      const content = readFileSync(absPath, 'utf-8');
+      return { content, path: relPath };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
+  write_file: async (args, opts = {}) => {
+    const { path: relPath, absPath } = getPath(args, opts);
+    const content = typeof args.content === 'string' ? args.content : String(args?.content ?? '');
+    if (!relPath) return { success: false, error: 'Error: empty path' };
+    try {
+      mkdirSync(dirname(absPath), { recursive: true });
+      writeFileSync(absPath, content, 'utf-8');
+      return { success: true, path: relPath };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  },
+  search_replace: async (args, opts = {}) => {
+    const { path: relPath, absPath } = getPath(args, opts);
+    const oldStr = typeof args.old_string === 'string' ? args.old_string : String(args?.old_string ?? '');
+    const newStr = typeof args.new_string === 'string' ? args.new_string : String(args?.new_string ?? '');
+    if (!relPath) return { success: false, error: 'Error: empty path' };
+    try {
+      if (!existsSync(absPath)) return { success: false, error: 'File not found' };
+      const content = readFileSync(absPath, 'utf-8');
+      const idx = content.indexOf(oldStr);
+      if (idx === -1) return { success: false, error: 'old_string not found in file' };
+      const newContent = content.slice(0, idx) + newStr + content.slice(idx + oldStr.length);
+      writeFileSync(absPath, newContent, 'utf-8');
+      return { success: true, path: relPath };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  },
+  delete_file: async (args, opts = {}) => {
+    const { path: relPath, absPath } = getPath(args, opts);
+    if (!relPath) return { success: false, error: 'Error: empty path' };
+    try {
+      if (!existsSync(absPath)) return { success: false, error: 'File not found' };
+      const stat = statSync(absPath);
+      if (!stat.isFile()) return { success: false, error: 'Not a file (use run_terminal_command to remove directories)' };
+      unlinkSync(absPath);
+      return { success: true, path: relPath };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  },
+  list_dir: async (args, opts = {}) => {
+    const cwd = opts.cwd ?? process.cwd();
+    const raw = typeof args.path === 'string' ? args.path : String(args?.path ?? '');
+    const dirPath = raw.trim() || '.';
+    const targetAbs = resolve(cwd, dirPath);
+    try {
+      if (!existsSync(targetAbs)) return { error: 'Directory not found' };
+      const stat = statSync(targetAbs);
+      if (!stat.isDirectory()) return { error: 'Not a directory' };
+      const entries = readdirSync(targetAbs, { withFileTypes: true });
+      const list = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+      return { path: dirPath, entries: list };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
   run_terminal_command: async (args, opts = {}) => {
     const command = typeof args.command === 'string' ? args.command : String(args?.command ?? '');
     const cwd = typeof args.cwd === 'string' ? args.cwd : opts.cwd ?? process.cwd();