neoagent 2.5.2-beta.22 → 2.5.2-beta.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neoagent",
-  "version": "2.5.2-beta.22",
+  "version": "2.5.2-beta.24",
   "description": "Proactive personal AI agent with no limits",
   "license": "AGPL-3.0-only",
   "main": "server/index.js",

package/server/public/.last_build_id

@@ -1 +1 @@
-7b68be842f70ebca5228682c4fe3dc90
+6cae41f1f3b746d64f017898666a06bd

package/server/public/flutter_bootstrap.js

@@ -37,6 +37,6 @@ _flutter.buildConfig = {"engineRevision":"77e2e94772b6eb43759e34ed1ad7da4674e19c
 
 _flutter.loader.load({
   serviceWorkerSettings: {
-    serviceWorkerVersion: "1027370389" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
+    serviceWorkerVersion: "571651995" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
   }
 });

package/server/public/main.dart.js

@@ -134794,7 +134794,7 @@ r===$&&A.b()
 p.push(A.jP(q,A.j9(!1,new A.a_(B.uG,A.d8(new A.cA(B.jt,new A.a7N(r,q),q),q,q),q),!1,B.H,!0),q,q,0,0,0,q))}r=!1
 if(!s.ay)if(!s.ch){r=s.e
 r===$&&A.b()
-r=B.b.u("mqgt278r-971ca3d").length!==0&&r.b}if(r){r=s.d
+r=B.b.u("mqgvaivu-1294860").length!==0&&r.b}if(r){r=s.d
 r===$&&A.b()
 r=r.aP&&!r.ai?84:0
 s=s.e
@@ -140506,7 +140506,7 @@ $S:0}
 A.a_6.prototype={}
 A.SQ.prototype={
 nb(a){var s=this
-if(B.b.u("mqgt278r-971ca3d").length===0||s.a!=null)return
+if(B.b.u("mqgvaivu-1294860").length===0||s.a!=null)return
 s.AU()
 s.a=A.on(B.RH,new A.bc8(s))},
 AU(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f
@@ -140524,7 +140524,7 @@ if(!t.f.b(k)){s=1
 break}i=J.a3(k,"buildId")
 h=i==null?null:B.b.u(J.p(i))
 j=h==null?"":h
-if(J.bi(j)===0||J.d(j,"mqgt278r-971ca3d")){s=1
+if(J.bi(j)===0||J.d(j,"mqgvaivu-1294860")){s=1
 break}n.b=!0
 n.F()
 p=2
@@ -140541,7 +140541,7 @@ case 2:return A.i(o.at(-1),r)}})
 return A.k($async$AU,r)},
 vE(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f,e,d,c,b,a,a0,a1
 var $async$vE=A.h(function(a2,a3){if(a2===1){o.push(a3)
-s=p}for(;;)switch(s){case 0:if(B.b.u("mqgt278r-971ca3d").length===0||n.c){s=1
+s=p}for(;;)switch(s){case 0:if(B.b.u("mqgvaivu-1294860").length===0||n.c){s=1
 break}n.c=!0
 n.F()
 p=4

package/server/services/ai/loop/conversation_loop.js

@@ -257,7 +257,13 @@ function summarizeReadTargets(toolExecutions = []) {
     if (!item || item.stateChanged) continue; // only read-only steps
     const input = item.input || {};
     let target = '';
-    if (typeof input.path === 'string' && input.path.trim()) {
+    if (Array.isArray(input.files) && input.files.length) {
+      target = input.files
+        .map((file) => (typeof file === 'string' ? file : file?.path || file?.file_path || ''))
+        .filter(Boolean)
+        .slice(0, 3)
+        .join(', ');
+    } else if (typeof input.path === 'string' && input.path.trim()) {
       target = input.path.trim();
     } else if (typeof input.command === 'string') {
       const files = input.command.match(/[\w./-]+\.(?:js|ts|tsx|jsx|py|dart|json|md|kt|c|h|ya?ml|sql|txt|sh)\b/g);
@@ -919,6 +925,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
     tools = selectInitialTools(allTools, analysis.suggested_tools, {
       widgetId: options.widgetId || null,
+      includeCoreFileTools: analysis.mode === 'execute' || analysis.mode === 'plan_execute',
     });
     engine.initializeToolRuntime(runId, allTools, tools, options);
     messages.push({
@@ -928,6 +935,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         buildToolCatalog(allTools),
         '',
         `Active tools: ${tools.map((tool) => tool.name).join(', ')}`,
+        'For workspace file inspection/editing, prefer read_files, read_file, search_files, list_directory, edit_file, replace_file_range, and write_file over shell cat/sed/python snippets. Use execute_command for git, tests, package managers, builds, and other shell-native actions.',
         'Use activate_tools with exact catalog names when another schema is required.',
       ].join('\n'),
     });

package/server/services/ai/loop/progress_monitor.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const FIRST_UPDATE_MS = 35 * 1000;
+const FIRST_UPDATE_MS = 30 * 1000;
 const REPEAT_UPDATE_MS = 75 * 1000;
 const STALL_MS = 150 * 1000;
 const TICK_MS = 15 * 1000;

package/server/services/ai/loop/tool_dispatch.js

@@ -20,6 +20,7 @@ function isReadOnlyToolCall(toolCall) {
   const name = String(toolCall?.function?.name || '');
   const readOnly = new Set([
     'read_file',
+    'read_files',
     'list_directory',
     'search_files',
     'code_navigate',

package/server/services/ai/messagingFallback.js

@@ -81,7 +81,7 @@ function parseToolExecutionSummary(item) {
 function toolWorkDescription(toolName) {
   const name = String(toolName || '');
   if (name === 'execute_command') return 'ran shell commands';
-  if (name === 'read_file' || name === 'search_files' || name === 'list_directory') return 'checked files';
+  if (name === 'read_file' || name === 'read_files' || name === 'search_files' || name === 'list_directory') return 'checked files';
   if (name === 'web_search' || name === 'http_request') return 'looked up supporting information';
   if (name.startsWith('browser_')) return 'checked the browser state';
   if (name.startsWith('android_')) return 'checked the Android state';

package/server/services/ai/preModelCompaction.js

@@ -159,6 +159,35 @@ function compactReadFileResult(result) {
   };
 }
 
+function compactReadFilesResult(result) {
+  const source = result && typeof result === 'object' ? result : {};
+  const rawLength = JSON.stringify(source).length;
+  const results = Array.isArray(source.results)
+    ? source.results.slice(0, 8).map((item) => {
+        const compacted = compactTextPayload(item?.content || '', {
+          maxChars: 900,
+          maxLines: 25,
+        });
+        return {
+          ...item,
+          content: compacted.text,
+        };
+      })
+    : [];
+  const next = { ...source, results };
+  const compactedLength = JSON.stringify(next).length;
+  return {
+    result: next,
+    metrics: {
+      inputChars: rawLength,
+      outputChars: compactedLength,
+      reducedChars: Math.max(0, rawLength - compactedLength),
+      applied: compactedLength !== rawLength,
+      strategies: compactedLength !== rawLength ? ['batch_file_result_truncation'] : [],
+    },
+  };
+}
+
 function compactPayloadForModel(toolName, result) {
   switch (String(toolName || '').trim()) {
     case 'http_request':
@@ -170,6 +199,8 @@ function compactPayloadForModel(toolName, result) {
       return compactSearchResult(result);
     case 'read_file':
       return compactReadFileResult(result);
+    case 'read_files':
+      return compactReadFilesResult(result);
     default:
       return {
         result,

package/server/services/ai/systemPrompt.js

@@ -190,7 +190,7 @@ SKILLS
 Create or improve a skill only when it is clearly reusable, polished, and likely to matter again. Most completed tasks should not become skills.
 
 GITHUB
-When working with a GitHub repository's code (reading files, exploring structure, analysing a codebase), prefer cloning it locally with execute_command (git clone https://github.com/owner/repo /tmp/repo-name) and then using read_file, list_directory, and search_files on the local clone. File-by-file GitHub API calls are slow and hit rate limits fast.
+When working with a GitHub repository's code (reading files, exploring structure, analysing a codebase), prefer cloning it locally with execute_command (git clone https://github.com/owner/repo /tmp/repo-name) and then using read_files, read_file, list_directory, search_files, edit_file, and replace_file_range on the local clone. File-by-file GitHub API calls are slow and hit rate limits fast.
 Use github_api_request for metadata and structured GitHub data (issues, PRs, commits, releases, CI runs, repo stats). When calling github_api_request, the path must be the FULL API path starting from the root, e.g. /repos/NeoLabs-Systems/NeoAgent/git/trees/main?recursive=1. You can also pass owner_repo="owner/repo" together with a relative path like /git/trees/main and the prefix is prepended automatically.
 Never fetch a repo's full file tree through the GitHub API when you actually need to read the code — clone it instead.
 

package/server/services/ai/taskAnalysis.js

@@ -45,6 +45,7 @@ const PLAN_SCHEMA_EXAMPLE = {
 const ANALYSIS_PROMPT_INSTRUCTIONS = [
   'Choose the lightest routing mode that still handles the task well.',
   'Use mode="direct_answer" only when a final user-facing reply can be given immediately without tool work.',
+  'For short immediate questions, greetings, small explanations, or quick conversational replies, prefer mode="direct_answer" with progress_update_policy="none"; speed matters more than creating plans or tasks.',
   'Use mode="execute" for normal tool-driven work without a separate planning step.',
   'Use mode="plan_execute" only when the task is genuinely multi-step, broad, or coordination-heavy.',
   'Set needs_verification=true when the final answer should be checked against tool evidence before it is sent.',
@@ -54,6 +55,7 @@ const ANALYSIS_PROMPT_INSTRUCTIONS = [
   'Set complexity from the actual work shape, not from keywords: simple, standard, or complex.',
   'Set autonomy_level="high" when the agent should decide sequencing, retries, evidence gathering, and verification without asking the user unless blocked.',
   'Set progress_update_policy="required" for long, slow, voice, messaging, or externally visible work where silence would be confusing.',
+  'Do not suggest create_task, update_task, delete_task, or list_tasks for ordinary immediate work. Use task tools only when the user asks for future, recurring, scheduled, monitored, background, or existing-task management behavior.',
   'Set parallel_work=true when independent tool calls or subagents can materially reduce latency.',
   'Set completion_confidence_required="high" when wrong completion would be costly, state-changing, user-visible, or hard to recover.',
 ];
@@ -82,9 +84,10 @@ const VERIFIER_PROMPT_INSTRUCTIONS = [
 const EXECUTION_GUIDANCE_ACTION_LINES = [
   'Act end-to-end. Run independent searches or inspections in parallel when possible. Prefer native integration tools and structured APIs over browser automation or shell scraping. Use exact IDs and required parameters; list or search first when you do not have them.',
   'For GitHub issue implementation or PR work, fetch the issue once, then establish or reuse a writable local checkout, create a task branch, inspect/edit/test locally, and push/open the PR. Use direct GitHub file mutation tools only as a fallback when a local checkout is unavailable.',
-  'Your shell (execute_command) starts in your workspace, and the file tools (read_file, write_file, list_directory, search_files) operate on that same workspace. Clone or create files into the current directory and then inspect or edit them with either the shell or the file tools interchangeably. Clone a repo once and reuse it; do not re-clone or re-list the same tree.',
+  'Your shell (execute_command) starts in your workspace, and the file tools (read_file, read_files, write_file, edit_file, replace_file_range, list_directory, search_files) operate on that same workspace. Clone or create files into the current directory, then prefer file tools for inspection and edits instead of shell cat/sed/python snippets. Clone a repo once and reuse it; do not re-clone or re-list the same tree.',
   'Tool results are already present in the conversation as tool output. Do not assume a tool result was persisted to a readable /tmp path unless that exact path was explicitly returned by the tool result.',
   'Use send_interim_update sparingly when a short real update or question would help.',
+  'Do not create background tasks for immediate short work. Answer directly unless the user asked to schedule, repeat, monitor, defer, or manage a saved task.',
   'When you must ask for missing required user input, ask once, then wait for the reply instead of re-asking in the same run.',
   'For outbound messages, calls, emails, shared edits, installs, restarts, or task mutations, verify the action result before claiming it happened. If user confirmation is required and missing, draft or ask instead of sending.',
   'Retry with alternative tools or approaches when one path fails. If evidence is still insufficient, say so explicitly instead of guessing.',

package/server/services/ai/toolEvidence.js

@@ -23,7 +23,7 @@ const EVIDENCE_SOURCE_RULES = [
   { source: 'memory', match: (name) => name.startsWith('memory_') || name === 'session_search' },
   { source: 'search', match: (name) => name === 'web_search' },
   { source: 'http', match: (name) => name === 'http_request' },
-  { source: 'files', match: (name) => ['read_file', 'search_files', 'list_directory', 'write_file', 'edit_file', 'code_navigate', 'query_structured_data'].includes(name) },
+  { source: 'files', match: (name) => ['read_file', 'read_files', 'search_files', 'list_directory', 'write_file', 'edit_file', 'replace_file_range', 'code_navigate', 'query_structured_data'].includes(name) },
   { source: 'command', match: (name) => name === 'execute_command' },
   { source: 'skills', match: (name) => name.includes('skill') },
   { source: 'tasks', match: (name) => name === 'create_task' || name === 'update_task' || name === 'delete_task' || name === 'list_tasks' || name.includes('widget') },
@@ -45,6 +45,7 @@ function classifyToolExecution(toolName, toolArgs = {}, result, errorMessage = '
     'web_search',
     'http_request',
     'read_file',
+    'read_files',
     'search_files',
     'list_directory',
     'code_navigate',
@@ -63,6 +64,7 @@ function classifyToolExecution(toolName, toolArgs = {}, result, errorMessage = '
     'execute_command',
     'write_file',
     'edit_file',
+    'replace_file_range',
     'send_interim_update',
     'send_message',
     'make_call',

package/server/services/ai/toolResult.js

@@ -91,6 +91,35 @@ function compactToolResult(toolName, toolArgs = {}, toolResult, options = {}) {
       });
       break;
 
+    case 'read_files':
+      envelope = trimObject({
+        tool: toolName,
+        count: toolResult?.count || 0,
+        truncated: toolResult?.truncated || false,
+        results: (toolResult?.results || []).slice(0, 6).map((item) => trimObject({
+          path: item.path || item.requestedPath,
+          requestedPath: item.requestedPath,
+          rangeShown: item.rangeShown,
+          error: item.error,
+          content: lineExcerpt(item.content || '', 10, Math.floor(softLimit * 0.22))
+        }))
+      });
+      break;
+
+    case 'replace_file_range':
+      envelope = trimObject({
+        tool: toolName,
+        status: toolResult?.success === false || toolResult?.error ? 'error' : 'ok',
+        path: toolResult?.path || toolArgs.path,
+        startLine: toolResult?.startLine || toolArgs.start_line,
+        endLine: toolResult?.endLine || toolArgs.end_line,
+        replacedLines: toolResult?.replacedLines,
+        insertedLines: toolResult?.insertedLines,
+        totalLines: toolResult?.totalLines,
+        error: toolResult?.error
+      });
+      break;
+
     case 'search_files':
       envelope = trimObject({
         tool: toolName,

package/server/services/ai/toolSelector.js

@@ -15,6 +15,22 @@ const ALWAYS_INCLUDE_BUILT_INS = [
   'send_message',
   'send_interim_update',
 ];
+const CORE_FILE_TOOLS = [
+  'read_file',
+  'read_files',
+  'list_directory',
+  'search_files',
+  'edit_file',
+  'replace_file_range',
+  'write_file',
+];
+
+function requiredToolNames(options = {}) {
+  const requiredNames = [...ALWAYS_INCLUDE_BUILT_INS];
+  if (options.widgetId) requiredNames.push('save_widget_snapshot');
+  if (options.includeCoreFileTools) requiredNames.push(...CORE_FILE_TOOLS);
+  return requiredNames;
+}
 
 function compactDescription(value, maxChars = 180) {
   const text = String(value || '').replace(/\s+/g, ' ').trim();
@@ -37,8 +53,7 @@ function buildToolCatalog(tools = []) {
 
 function ensureRequiredTools(selectedTools = [], builtInTools = [], options = {}) {
   const limit = Number(options.maxTools) || MAX_TOOLS;
-  const requiredNames = [...ALWAYS_INCLUDE_BUILT_INS];
-  if (options.widgetId) requiredNames.push('save_widget_snapshot');
+  const requiredNames = requiredToolNames(options);
   if (!requiredNames.length) return selectedTools;
 
   const selected = Array.isArray(selectedTools) ? [...selectedTools] : [];
@@ -83,6 +98,7 @@ function selectInitialTools(allTools = [], suggestedNames = [], options = {}) {
 
 function activateTools(currentTools = [], allTools = [], requestedNames = [], options = {}) {
   const knownByName = new Map(allTools.map((tool) => [tool?.name, tool]));
+  const requiredNames = requiredToolNames(options);
   let next = ensureRequiredTools(currentTools, allTools, options);
   const activated = [];
   const evicted = [];
@@ -102,7 +118,7 @@ function activateTools(currentTools = [], allTools = [], requestedNames = [], op
     if (next.some((item) => item?.name === name)) continue;
     if (next.length >= MAX_TOOLS) {
       const replaceIndex = next.findIndex((item) => (
-        !ALWAYS_INCLUDE_BUILT_INS.includes(item?.name)
+        !requiredNames.includes(item?.name)
         && !requested.includes(item?.name)
       ));
       if (replaceIndex === -1) {
@@ -136,6 +152,7 @@ function selectToolsForTask(task, builtInTools = [], mcpTools = [], _options = {
 }
 
 module.exports = {
+  CORE_FILE_TOOLS,
   MAX_TOOLS,
   activateTools,
   buildToolCatalog,

package/server/services/ai/tools.js

@@ -896,6 +896,34 @@ function getAvailableTools(app, options = {}) {
                 required: []
             }
         },
+        {
+            name: 'read_files',
+            description: 'Read multiple workspace files or line ranges in one call. Prefer this over several read_file, cat, or sed commands when inspecting related files. This cannot read VM /tmp files created by execute_command.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    files: {
+                        type: 'array',
+                        description: 'Files to read. Each item accepts path or file_path plus optional start_line/end_line or line_start/line_count.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                path: { type: 'string', description: 'Absolute or relative path inside the per-user workspace' },
+                                file_path: { type: 'string', description: 'Alias for path' },
+                                start_line: { type: 'number', description: 'Starting line number (1-indexed, inclusive)' },
+                                end_line: { type: 'number', description: 'Ending line number (1-indexed, inclusive)' },
+                                line_start: { type: 'number', description: 'Alias for start_line' },
+                                line_count: { type: 'number', description: 'Number of lines to read from start_line/line_start' },
+                                encoding: { type: 'string', description: 'File encoding (default utf-8)' }
+                            },
+                            required: []
+                        }
+                    },
+                    encoding: { type: 'string', description: 'Default file encoding for items without encoding (default utf-8)' }
+                },
+                required: ['files']
+            }
+        },
         {
             name: 'write_file',
             description: 'Write or append content to a file. Creates parent directories if they do not exist. IMPORTANT: When writing markdown or code, ensure proper formatting and avoid truncating or overly summarizing content. Write complete, well-formatted, detailed files.',
@@ -932,6 +960,20 @@ function getAvailableTools(app, options = {}) {
                 required: ['path', 'edits']
             }
         },
+        {
+            name: 'replace_file_range',
+            description: 'Replace a 1-indexed inclusive line range in a workspace file. Use this when you know line numbers and exact-text edit_file would be brittle. Read the target range first, then replace only the intended lines.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path inside the per-user workspace' },
+                    start_line: { type: 'number', description: 'Starting line number (1-indexed, inclusive)' },
+                    end_line: { type: 'number', description: 'Ending line number (1-indexed, inclusive)' },
+                    content: { type: 'string', description: 'Replacement content for the range. Empty string deletes the range.' }
+                },
+                required: ['path', 'start_line', 'end_line', 'content']
+            }
+        },
         {
             name: 'list_directory',
             description: 'List files and directories with metadata (size, modified time).',
@@ -1144,7 +1186,7 @@ function getAvailableTools(app, options = {}) {
         },
         {
             name: 'create_task',
-            description: 'Create a background task with a named trigger and self-contained prompt.',
+            description: 'Create a future, recurring, monitored, or background automation with a named trigger and self-contained prompt. Do not use for immediate short answers.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -1163,12 +1205,12 @@ function getAvailableTools(app, options = {}) {
         },
         {
             name: 'list_tasks',
-            description: 'List all tasks for this user and agent.',
+            description: 'List saved background/scheduled tasks for this user and agent. Do not use for ordinary immediate replies.',
             parameters: { type: 'object', properties: {} }
         },
         {
             name: 'delete_task',
-            description: 'Delete a task by its ID.',
+            description: 'Delete a saved background/scheduled task by its ID.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -1179,7 +1221,7 @@ function getAvailableTools(app, options = {}) {
         },
         {
             name: 'update_task',
-            description: 'Update an existing task, including its trigger, prompt, or enabled state.',
+            description: 'Update an existing saved background/scheduled task, including its trigger, prompt, or enabled state.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -2339,6 +2381,49 @@ async function executeTool(toolName, args, context, engine) {
             }
         }
 
+        case 'read_files': {
+            try {
+                const workspace = wc();
+                if (!workspace) return { error: 'Workspace service is unavailable.' };
+                const entries = Array.isArray(args.files) ? args.files : [];
+                if (!entries.length) {
+                    return { error: 'read_files requires a non-empty files array.' };
+                }
+                const maxFiles = 8;
+                const results = entries.slice(0, maxFiles).map((entry, index) => {
+                    const fileArgs = typeof entry === 'string'
+                        ? { path: entry }
+                        : (entry && typeof entry === 'object' ? entry : {});
+                    const normalizedArgs = normalizeReadFileArgs({
+                        ...fileArgs,
+                        encoding: fileArgs.encoding || args.encoding || 'utf-8',
+                    });
+                    if (!normalizedArgs.path) {
+                        return {
+                            index,
+                            success: false,
+                            error: 'Each read_files item requires path or file_path.',
+                        };
+                    }
+                    const result = workspace.readFile(userId, normalizedArgs);
+                    return {
+                        index,
+                        requestedPath: normalizedArgs.path,
+                        success: !result?.error,
+                        ...result,
+                    };
+                });
+                return {
+                    success: results.every((result) => result.success !== false && !result.error),
+                    count: results.length,
+                    truncated: entries.length > maxFiles,
+                    results,
+                };
+            } catch (err) {
+                return { error: err.message };
+            }
+        }
+
         case 'write_file': {
             try {
                 const workspace = wc();
@@ -2366,6 +2451,24 @@ async function executeTool(toolName, args, context, engine) {
             }
         }
 
+        case 'replace_file_range': {
+            try {
+                const workspace = wc();
+                if (!workspace) return { error: 'Workspace service is unavailable.' };
+                if (typeof workspace.replaceFileRange !== 'function') {
+                    return { error: 'Workspace service does not support replace_file_range.' };
+                }
+                return workspace.replaceFileRange(userId, {
+                    path: args.path,
+                    start_line: args.start_line ?? args.startLine,
+                    end_line: args.end_line ?? args.endLine,
+                    content: args.content,
+                });
+            } catch (err) {
+                return { error: err.message };
+            }
+        }
+
         case 'list_directory': {
             try {
                 const workspace = wc();

package/server/services/workspace/manager.js

@@ -294,6 +294,61 @@ class WorkspaceManager {
     }
   }
 
+  replaceFileRange(userId, options = {}) {
+    let filePath;
+    try {
+      filePath = this.resolvePath(userId, options.path || '', 'path');
+      if (!fs.existsSync(filePath)) {
+        return { success: false, error: `File not found: ${filePath}`, path: filePath };
+      }
+
+      const start = Number(options.start_line ?? options.startLine);
+      const end = Number(options.end_line ?? options.endLine ?? start);
+      if (!Number.isInteger(start) || start < 1) {
+        return { success: false, error: 'start_line must be a positive integer', path: filePath };
+      }
+      if (!Number.isInteger(end) || end < 1) {
+        return { success: false, error: 'end_line must be a positive integer', path: filePath };
+      }
+      if (start > end) {
+        return { success: false, error: 'start_line must be less than or equal to end_line', path: filePath };
+      }
+
+      const original = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+      const hadFinalNewline = original.endsWith('\n');
+      const lines = original.split('\n');
+      if (hadFinalNewline) lines.pop();
+      const totalLines = Math.max(lines.length, 1);
+      if (start > totalLines || end > totalLines) {
+        return {
+          success: false,
+          error: `line range ${start}-${end} is outside file with ${totalLines} lines`,
+          path: filePath,
+          totalLines,
+        };
+      }
+
+      const replacementText = String(options.content ?? '').replace(/\r\n/g, '\n');
+      const replacementLines = replacementText === ''
+        ? []
+        : replacementText.replace(/\n$/, '').split('\n');
+      lines.splice(start - 1, end - start + 1, ...replacementLines);
+      const next = `${lines.join('\n')}${hadFinalNewline ? '\n' : ''}`;
+      fs.writeFileSync(filePath, next, 'utf8');
+      return {
+        success: true,
+        path: filePath,
+        startLine: start,
+        endLine: end,
+        replacedLines: end - start + 1,
+        insertedLines: replacementLines.length,
+        totalLines: lines.length,
+      };
+    } catch (err) {
+      return { success: false, path: filePath || null, error: err.message };
+    }
+  }
+
   listDirectory(userId, options = {}) {
     const dirPath = this.resolvePath(userId, options.path || '.', 'path');
     const depthValue = options.depth != null ? Number(options.depth) : (options.recursive ? 3 : 1);