@aigne/core 1.72.0-beta.4 → 1.72.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.72.0-beta.5](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.72.0-beta.4...core-v1.72.0-beta.5) (2025-12-25)
+
+
+### Bug Fixes
+
+* **core:** afs skills improvements ([#849](https://github.com/AIGNE-io/aigne-framework/issues/849)) ([557cc8b](https://github.com/AIGNE-io/aigne-framework/commit/557cc8b4b72f0e91ad654556f47bbe0ad0ececdb))
+
 ## [1.72.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.72.0-beta.3...core-v1.72.0-beta.4) (2025-12-24)
 
 

package/lib/cjs/prompt/skills/afs/edit.d.ts

@@ -1,21 +1,17 @@
 import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
 import { AFSSkillBase } from "./base.js";
-export interface Patch {
-    start_line: number;
-    end_line: number;
-    replace?: string;
-    delete: boolean;
-}
 export interface AFSEditInput extends Message {
     path: string;
-    patches: Patch[];
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
 }
 export interface AFSEditOutput extends Message {
     status: string;
     tool: string;
     path: string;
     message: string;
-    data: string;
+    snippet: string;
 }
 export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditOutput> {
     afs: NonNullable<AgentOptions<AFSEditInput, AFSEditOutput>["afs"]>;
@@ -23,5 +19,6 @@ export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditO
 export declare class AFSEditAgent extends AFSSkillBase<AFSEditInput, AFSEditOutput> {
     constructor(options: AFSEditAgentOptions);
     process(input: AFSEditInput, _options: AgentInvokeOptions): Promise<AFSEditOutput>;
-    applyCustomPatches(text: string, patches: Patch[]): string;
+    private countOccurrences;
+    private extractSnippet;
 }

package/lib/cjs/prompt/skills/afs/edit.js

@@ -3,119 +3,122 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFSEditAgent = void 0;
 const zod_1 = require("zod");
 const base_js_1 = require("./base.js");
+const CONTEXT_LINES = 4; // Number of lines to show before and after the edit
 class AFSEditAgent extends base_js_1.AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_edit",
-            description: `Apply precise line-based patches to modify files in the Agentic File System (AFS)
-- Performs targeted edits using line numbers without rewriting the entire file
-- Supports both replacing and deleting line ranges
-- Multiple patches can be applied in a single operation
+            description: `Performs exact string replacements in files within the Agentic File System (AFS).
 
 Usage:
+- You must use afs_read at least once before editing to understand the file content
 - The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md")
-- This is NOT a local system file path - it operates within the AFS virtual file system
-- IMPORTANT: You MUST use afs_read with withLineNumbers=true before editing to get accurate line numbers
-- Line numbers are 0-based: first line is 0, second line is 1, etc.
-- The range [start_line, end_line) is exclusive on end_line`,
+- Preserve exact indentation (tabs/spaces) as it appears in the file
+- The edit will FAIL if oldString is not found in the file
+- The edit will FAIL if oldString appears multiple times (unless replaceAll is true)
+- Use replaceAll to replace/rename strings across the entire file`,
             ...options,
             inputSchema: zod_1.z.object({
                 path: zod_1.z
                     .string()
                     .describe("Absolute AFS path to the file to edit (e.g., '/docs/readme.md'). Must start with '/'"),
-                patches: zod_1.z
-                    .array(zod_1.z.object({
-                    start_line: zod_1.z
-                        .number()
-                        .int()
-                        .describe("Start line number (0-based, inclusive). First line is 0"),
-                    end_line: zod_1.z
-                        .number()
-                        .int()
-                        .describe("End line number (0-based, exclusive). To edit line 5 only, use start_line=5, end_line=6"),
-                    replace: zod_1.z
-                        .string()
-                        .optional()
-                        .describe("New content to insert. Omit when delete=true"),
-                    delete: zod_1.z
-                        .boolean()
-                        .describe("Set to true to delete the line range. Set to false to replace with 'replace' content"),
-                }))
-                    .min(1)
-                    .describe("Array of patches to apply. Each patch specifies a line range and the operation (delete or replace)"),
+                oldString: zod_1.z
+                    .string()
+                    .describe("The exact text to replace. Must match file content exactly including whitespace"),
+                newString: zod_1.z
+                    .string()
+                    .describe("The text to replace it with (must be different from oldString)"),
+                replaceAll: zod_1.z
+                    .boolean()
+                    .optional()
+                    .default(false)
+                    .describe("Replace all occurrences of oldString (default: false)"),
             }),
             outputSchema: zod_1.z.object({
                 status: zod_1.z.string(),
                 tool: zod_1.z.string(),
                 path: zod_1.z.string(),
                 message: zod_1.z.string(),
-                data: zod_1.z.string(),
+                snippet: zod_1.z.string(),
             }),
         });
     }
     async process(input, _options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        if (!input.patches?.length) {
-            throw new Error("No patches provided for afs_edit.");
+        const { path, oldString, newString, replaceAll = false } = input;
+        if (oldString === newString) {
+            throw new Error("oldString and newString must be different");
         }
-        const readResult = await this.afs.read(input.path);
+        const readResult = await this.afs.read(path);
         if (!readResult.data?.content || typeof readResult.data.content !== "string") {
-            throw new Error(`Cannot read file content from: ${input.path}`);
+            throw new Error(`Cannot read file content from: ${path}`);
         }
         const originalContent = readResult.data.content;
-        const updatedContent = this.applyCustomPatches(originalContent, input.patches);
-        await this.afs.write(input.path, {
+        // Check if oldString exists in the file
+        const occurrences = this.countOccurrences(originalContent, oldString);
+        if (occurrences === 0) {
+            throw new Error(`oldString not found in file: ${path}`);
+        }
+        if (occurrences > 1 && !replaceAll) {
+            throw new Error(`oldString appears ${occurrences} times in file. Use replaceAll=true to replace all occurrences, or provide more context to make oldString unique.`);
+        }
+        // Find the position of the first occurrence for snippet extraction
+        const firstOccurrenceIndex = originalContent.indexOf(oldString);
+        // Perform the replacement
+        const updatedContent = replaceAll
+            ? originalContent.split(oldString).join(newString)
+            : originalContent.replace(oldString, newString);
+        await this.afs.write(path, {
             content: updatedContent,
         });
+        // Generate snippet around the edit location
+        const snippet = this.extractSnippet(updatedContent, firstOccurrenceIndex, newString.length);
+        const replacementCount = replaceAll ? occurrences : 1;
         return {
             status: "success",
             tool: "afs_edit",
-            path: input.path,
-            message: `Applied ${input.patches.length} patches to ${input.path}`,
-            data: updatedContent,
+            path,
+            message: `Replaced ${replacementCount} occurrence${replacementCount > 1 ? "s" : ""} in ${path}`,
+            snippet,
         };
     }
-    applyCustomPatches(text, patches) {
-        // Sort by start_line to ensure sequential application
-        const sorted = [...patches].sort((a, b) => a.start_line - b.start_line);
-        const lines = text.split("\n");
-        for (let i = 0; i < sorted.length; i++) {
-            const patch = sorted[i];
-            if (!patch)
-                continue;
-            const start = patch.start_line;
-            const end = patch.end_line;
-            const deleteCount = end - start; // [start, end) range
-            let delta = 0;
-            if (patch.delete) {
-                // Delete mode: remove the specified lines [start, end)
-                lines.splice(start, deleteCount);
-                delta = -deleteCount;
-            }
-            else {
-                // Replace mode: replace the specified lines with new content
-                const replaceLines = patch.replace ? patch.replace.split("\n") : [];
-                lines.splice(start, deleteCount, ...replaceLines);
-                delta = replaceLines.length - deleteCount;
-            }
-            // Update subsequent patches' line numbers
-            // For exclusive-end semantics [start, end), we adjust patches that start >= current patch's start_line
-            // after the current patch has been applied
-            if (delta !== 0) {
-                for (let j = i + 1; j < sorted.length; j++) {
-                    const next = sorted[j];
-                    if (!next)
-                        continue;
-                    // Adjust patches that start at or after the current patch's end line
-                    if (next.start_line >= patch.end_line) {
-                        next.start_line += delta;
-                        next.end_line += delta;
-                    }
-                }
+    countOccurrences(text, search) {
+        let count = 0;
+        let position = text.indexOf(search);
+        while (position !== -1) {
+            count++;
+            position = text.indexOf(search, position + search.length);
+        }
+        return count;
+    }
+    extractSnippet(content, editStartIndex, newStringLength) {
+        const lines = content.split("\n");
+        // Find the line number where the edit starts
+        let charCount = 0;
+        let editStartLine = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const lineLength = (lines[i]?.length ?? 0) + 1; // +1 for newline
+            if (charCount + lineLength > editStartIndex) {
+                editStartLine = i;
+                break;
             }
+            charCount += lineLength;
         }
-        return lines.join("\n");
+        // Calculate how many lines the new content spans
+        const newContentLines = content
+            .substring(editStartIndex, editStartIndex + newStringLength)
+            .split("\n").length;
+        const editEndLine = editStartLine + newContentLines - 1;
+        // Extract lines with context
+        const startLine = Math.max(0, editStartLine - CONTEXT_LINES);
+        const endLine = Math.min(lines.length - 1, editEndLine + CONTEXT_LINES);
+        // Format with line numbers (1-based)
+        const snippetLines = lines.slice(startLine, endLine + 1).map((line, idx) => {
+            const lineNum = startLine + idx + 1;
+            return `${String(lineNum).padStart(4)}| ${line}`;
+        });
+        return snippetLines.join("\n");
     }
 }
 exports.AFSEditAgent = AFSEditAgent;

package/lib/cjs/prompt/skills/afs/read.d.ts

@@ -3,15 +3,19 @@ import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/
 import { AFSSkillBase } from "./base.js";
 export interface AFSReadInput extends Message {
     path: string;
-    withLineNumbers?: boolean;
+    offset?: number;
+    limit?: number;
 }
 export interface AFSReadOutput extends Message {
     status: string;
     tool: string;
     path: string;
-    withLineNumbers?: boolean;
     data?: AFSEntry;
     message?: string;
+    totalLines?: number;
+    returnedLines?: number;
+    truncated?: boolean;
+    offset?: number;
 }
 export interface AFSReadAgentOptions extends AgentOptions<AFSReadInput, AFSReadOutput> {
     afs: NonNullable<AgentOptions<AFSReadInput, AFSReadOutput>["afs"]>;

package/lib/cjs/prompt/skills/afs/read.js

@@ -3,37 +3,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFSReadAgent = void 0;
 const zod_1 = require("zod");
 const base_js_1 = require("./base.js");
+const DEFAULT_LINE_LIMIT = 2000;
+const MAX_LINE_LENGTH = 2000;
 class AFSReadAgent extends base_js_1.AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_read",
             description: `Read file contents from the Agentic File System (AFS)
-- Returns the complete content of a file at the specified AFS path
-- Supports line numbers output for precise editing references
-- Use this tool when you need to review, analyze, or understand file content
+- Returns the content of a file at the specified AFS path
+- By default reads up to ${DEFAULT_LINE_LIMIT} lines, use offset/limit for large files
+- Lines longer than ${MAX_LINE_LENGTH} characters will be truncated
 
 Usage:
-- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md", "/memory/user/notes")
-- This is NOT a local system file path - it operates within the AFS virtual file system
-- IMPORTANT: You MUST set withLineNumbers to true before using afs_edit, as line numbers are required for precise edits
-- Returns the file's content along with metadata (id, path, timestamps, etc.)`,
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md")
+- Use offset to start reading from a specific line (0-based)
+- Use limit to control number of lines returned (default: ${DEFAULT_LINE_LIMIT})
+- Check truncated field to know if file was partially returned`,
             ...options,
             inputSchema: zod_1.z.object({
                 path: zod_1.z
                     .string()
                     .describe("Absolute AFS path to the file to read (e.g., '/docs/readme.md'). Must start with '/'"),
-                withLineNumbers: zod_1.z
-                    .boolean()
+                offset: zod_1.z
+                    .number()
+                    .int()
+                    .min(0)
                     .optional()
-                    .describe("MUST be set to true before using afs_edit. Adds line numbers to output (format: '1| line content')"),
+                    .describe("Line number to start reading from (0-based, default: 0)"),
+                limit: zod_1.z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(DEFAULT_LINE_LIMIT)
+                    .optional()
+                    .describe(`Maximum number of lines to read (default: ${DEFAULT_LINE_LIMIT})`),
             }),
             outputSchema: zod_1.z.object({
                 status: zod_1.z.string(),
                 tool: zod_1.z.string(),
                 path: zod_1.z.string(),
-                withLineNumbers: zod_1.z.boolean().optional(),
                 data: zod_1.z.custom().optional(),
                 message: zod_1.z.string().optional(),
+                totalLines: zod_1.z.number().optional(),
+                returnedLines: zod_1.z.number().optional(),
+                truncated: zod_1.z.boolean().optional(),
+                offset: zod_1.z.number().optional(),
             }),
         });
     }
@@ -41,22 +55,44 @@ Usage:
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
         const result = await this.afs.read(input.path);
-        let content = result.data?.content;
-        if (input.withLineNumbers && typeof content === "string") {
-            content = content
-                .split("\n")
-                .map((line, idx) => `${idx + 1}| ${line}`)
-                .join("\n");
+        if (!result.data?.content || typeof result.data.content !== "string") {
+            return {
+                status: "success",
+                tool: "afs_read",
+                path: input.path,
+                ...result,
+            };
+        }
+        const offset = input.offset ?? 0;
+        const limit = input.limit ?? DEFAULT_LINE_LIMIT;
+        const allLines = result.data.content.split("\n");
+        const totalLines = allLines.length;
+        // Apply offset and limit
+        const selectedLines = allLines.slice(offset, offset + limit);
+        // Truncate long lines
+        const processedLines = selectedLines.map((line) => line.length > MAX_LINE_LENGTH ? `${line.substring(0, MAX_LINE_LENGTH)}... [truncated]` : line);
+        const returnedLines = processedLines.length;
+        const truncated = offset > 0 || offset + limit < totalLines;
+        const processedContent = processedLines.join("\n");
+        let message;
+        if (truncated) {
+            const startLine = offset + 1;
+            const endLine = offset + returnedLines;
+            message = `Showing lines ${startLine}-${endLine} of ${totalLines}. Use offset/limit to read more.`;
         }
         return {
             status: "success",
             tool: "afs_read",
             path: input.path,
-            withLineNumbers: input.withLineNumbers,
+            totalLines,
+            returnedLines,
+            truncated,
+            offset,
+            message,
             ...result,
-            data: result.data && {
+            data: {
                 ...result.data,
-                content,
+                content: processedContent,
             },
         };
     }

package/lib/cjs/prompt/skills/afs/write.js

@@ -43,7 +43,7 @@ Usage:
     async process(input, _options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        const result = await this.afs.write(input.path, {
+        const _result = await this.afs.write(input.path, {
             content: input.content,
         }, {
             append: input.append ?? false,
@@ -52,7 +52,7 @@ Usage:
             status: "success",
             tool: "afs_write",
             path: input.path,
-            ...result,
+            message: "File written successfully",
         };
     }
 }

package/lib/dts/prompt/skills/afs/edit.d.ts

@@ -1,21 +1,17 @@
 import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
 import { AFSSkillBase } from "./base.js";
-export interface Patch {
-    start_line: number;
-    end_line: number;
-    replace?: string;
-    delete: boolean;
-}
 export interface AFSEditInput extends Message {
     path: string;
-    patches: Patch[];
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
 }
 export interface AFSEditOutput extends Message {
     status: string;
     tool: string;
     path: string;
     message: string;
-    data: string;
+    snippet: string;
 }
 export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditOutput> {
     afs: NonNullable<AgentOptions<AFSEditInput, AFSEditOutput>["afs"]>;
@@ -23,5 +19,6 @@ export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditO
 export declare class AFSEditAgent extends AFSSkillBase<AFSEditInput, AFSEditOutput> {
     constructor(options: AFSEditAgentOptions);
     process(input: AFSEditInput, _options: AgentInvokeOptions): Promise<AFSEditOutput>;
-    applyCustomPatches(text: string, patches: Patch[]): string;
+    private countOccurrences;
+    private extractSnippet;
 }

package/lib/dts/prompt/skills/afs/read.d.ts

@@ -3,15 +3,19 @@ import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/
 import { AFSSkillBase } from "./base.js";
 export interface AFSReadInput extends Message {
     path: string;
-    withLineNumbers?: boolean;
+    offset?: number;
+    limit?: number;
 }
 export interface AFSReadOutput extends Message {
     status: string;
     tool: string;
     path: string;
-    withLineNumbers?: boolean;
     data?: AFSEntry;
     message?: string;
+    totalLines?: number;
+    returnedLines?: number;
+    truncated?: boolean;
+    offset?: number;
 }
 export interface AFSReadAgentOptions extends AgentOptions<AFSReadInput, AFSReadOutput> {
     afs: NonNullable<AgentOptions<AFSReadInput, AFSReadOutput>["afs"]>;

package/lib/esm/prompt/skills/afs/edit.d.ts

@@ -1,21 +1,17 @@
 import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
 import { AFSSkillBase } from "./base.js";
-export interface Patch {
-    start_line: number;
-    end_line: number;
-    replace?: string;
-    delete: boolean;
-}
 export interface AFSEditInput extends Message {
     path: string;
-    patches: Patch[];
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
 }
 export interface AFSEditOutput extends Message {
     status: string;
     tool: string;
     path: string;
     message: string;
-    data: string;
+    snippet: string;
 }
 export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditOutput> {
     afs: NonNullable<AgentOptions<AFSEditInput, AFSEditOutput>["afs"]>;
@@ -23,5 +19,6 @@ export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditO
 export declare class AFSEditAgent extends AFSSkillBase<AFSEditInput, AFSEditOutput> {
     constructor(options: AFSEditAgentOptions);
     process(input: AFSEditInput, _options: AgentInvokeOptions): Promise<AFSEditOutput>;
-    applyCustomPatches(text: string, patches: Patch[]): string;
+    private countOccurrences;
+    private extractSnippet;
 }

package/lib/esm/prompt/skills/afs/edit.js

@@ -1,117 +1,120 @@
 import { z } from "zod";
 import { AFSSkillBase } from "./base.js";
+const CONTEXT_LINES = 4; // Number of lines to show before and after the edit
 export class AFSEditAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_edit",
-            description: `Apply precise line-based patches to modify files in the Agentic File System (AFS)
-- Performs targeted edits using line numbers without rewriting the entire file
-- Supports both replacing and deleting line ranges
-- Multiple patches can be applied in a single operation
+            description: `Performs exact string replacements in files within the Agentic File System (AFS).
 
 Usage:
+- You must use afs_read at least once before editing to understand the file content
 - The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md")
-- This is NOT a local system file path - it operates within the AFS virtual file system
-- IMPORTANT: You MUST use afs_read with withLineNumbers=true before editing to get accurate line numbers
-- Line numbers are 0-based: first line is 0, second line is 1, etc.
-- The range [start_line, end_line) is exclusive on end_line`,
+- Preserve exact indentation (tabs/spaces) as it appears in the file
+- The edit will FAIL if oldString is not found in the file
+- The edit will FAIL if oldString appears multiple times (unless replaceAll is true)
+- Use replaceAll to replace/rename strings across the entire file`,
             ...options,
             inputSchema: z.object({
                 path: z
                     .string()
                     .describe("Absolute AFS path to the file to edit (e.g., '/docs/readme.md'). Must start with '/'"),
-                patches: z
-                    .array(z.object({
-                    start_line: z
-                        .number()
-                        .int()
-                        .describe("Start line number (0-based, inclusive). First line is 0"),
-                    end_line: z
-                        .number()
-                        .int()
-                        .describe("End line number (0-based, exclusive). To edit line 5 only, use start_line=5, end_line=6"),
-                    replace: z
-                        .string()
-                        .optional()
-                        .describe("New content to insert. Omit when delete=true"),
-                    delete: z
-                        .boolean()
-                        .describe("Set to true to delete the line range. Set to false to replace with 'replace' content"),
-                }))
-                    .min(1)
-                    .describe("Array of patches to apply. Each patch specifies a line range and the operation (delete or replace)"),
+                oldString: z
+                    .string()
+                    .describe("The exact text to replace. Must match file content exactly including whitespace"),
+                newString: z
+                    .string()
+                    .describe("The text to replace it with (must be different from oldString)"),
+                replaceAll: z
+                    .boolean()
+                    .optional()
+                    .default(false)
+                    .describe("Replace all occurrences of oldString (default: false)"),
             }),
             outputSchema: z.object({
                 status: z.string(),
                 tool: z.string(),
                 path: z.string(),
                 message: z.string(),
-                data: z.string(),
+                snippet: z.string(),
             }),
         });
     }
     async process(input, _options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        if (!input.patches?.length) {
-            throw new Error("No patches provided for afs_edit.");
+        const { path, oldString, newString, replaceAll = false } = input;
+        if (oldString === newString) {
+            throw new Error("oldString and newString must be different");
         }
-        const readResult = await this.afs.read(input.path);
+        const readResult = await this.afs.read(path);
         if (!readResult.data?.content || typeof readResult.data.content !== "string") {
-            throw new Error(`Cannot read file content from: ${input.path}`);
+            throw new Error(`Cannot read file content from: ${path}`);
         }
         const originalContent = readResult.data.content;
-        const updatedContent = this.applyCustomPatches(originalContent, input.patches);
-        await this.afs.write(input.path, {
+        // Check if oldString exists in the file
+        const occurrences = this.countOccurrences(originalContent, oldString);
+        if (occurrences === 0) {
+            throw new Error(`oldString not found in file: ${path}`);
+        }
+        if (occurrences > 1 && !replaceAll) {
+            throw new Error(`oldString appears ${occurrences} times in file. Use replaceAll=true to replace all occurrences, or provide more context to make oldString unique.`);
+        }
+        // Find the position of the first occurrence for snippet extraction
+        const firstOccurrenceIndex = originalContent.indexOf(oldString);
+        // Perform the replacement
+        const updatedContent = replaceAll
+            ? originalContent.split(oldString).join(newString)
+            : originalContent.replace(oldString, newString);
+        await this.afs.write(path, {
             content: updatedContent,
         });
+        // Generate snippet around the edit location
+        const snippet = this.extractSnippet(updatedContent, firstOccurrenceIndex, newString.length);
+        const replacementCount = replaceAll ? occurrences : 1;
         return {
             status: "success",
             tool: "afs_edit",
-            path: input.path,
-            message: `Applied ${input.patches.length} patches to ${input.path}`,
-            data: updatedContent,
+            path,
+            message: `Replaced ${replacementCount} occurrence${replacementCount > 1 ? "s" : ""} in ${path}`,
+            snippet,
         };
     }
-    applyCustomPatches(text, patches) {
-        // Sort by start_line to ensure sequential application
-        const sorted = [...patches].sort((a, b) => a.start_line - b.start_line);
-        const lines = text.split("\n");
-        for (let i = 0; i < sorted.length; i++) {
-            const patch = sorted[i];
-            if (!patch)
-                continue;
-            const start = patch.start_line;
-            const end = patch.end_line;
-            const deleteCount = end - start; // [start, end) range
-            let delta = 0;
-            if (patch.delete) {
-                // Delete mode: remove the specified lines [start, end)
-                lines.splice(start, deleteCount);
-                delta = -deleteCount;
-            }
-            else {
-                // Replace mode: replace the specified lines with new content
-                const replaceLines = patch.replace ? patch.replace.split("\n") : [];
-                lines.splice(start, deleteCount, ...replaceLines);
-                delta = replaceLines.length - deleteCount;
-            }
-            // Update subsequent patches' line numbers
-            // For exclusive-end semantics [start, end), we adjust patches that start >= current patch's start_line
-            // after the current patch has been applied
-            if (delta !== 0) {
-                for (let j = i + 1; j < sorted.length; j++) {
-                    const next = sorted[j];
-                    if (!next)
-                        continue;
-                    // Adjust patches that start at or after the current patch's end line
-                    if (next.start_line >= patch.end_line) {
-                        next.start_line += delta;
-                        next.end_line += delta;
-                    }
-                }
+    countOccurrences(text, search) {
+        let count = 0;
+        let position = text.indexOf(search);
+        while (position !== -1) {
+            count++;
+            position = text.indexOf(search, position + search.length);
+        }
+        return count;
+    }
+    extractSnippet(content, editStartIndex, newStringLength) {
+        const lines = content.split("\n");
+        // Find the line number where the edit starts
+        let charCount = 0;
+        let editStartLine = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const lineLength = (lines[i]?.length ?? 0) + 1; // +1 for newline
+            if (charCount + lineLength > editStartIndex) {
+                editStartLine = i;
+                break;
             }
+            charCount += lineLength;
         }
-        return lines.join("\n");
+        // Calculate how many lines the new content spans
+        const newContentLines = content
+            .substring(editStartIndex, editStartIndex + newStringLength)
+            .split("\n").length;
+        const editEndLine = editStartLine + newContentLines - 1;
+        // Extract lines with context
+        const startLine = Math.max(0, editStartLine - CONTEXT_LINES);
+        const endLine = Math.min(lines.length - 1, editEndLine + CONTEXT_LINES);
+        // Format with line numbers (1-based)
+        const snippetLines = lines.slice(startLine, endLine + 1).map((line, idx) => {
+            const lineNum = startLine + idx + 1;
+            return `${String(lineNum).padStart(4)}| ${line}`;
+        });
+        return snippetLines.join("\n");
     }
 }

package/lib/esm/prompt/skills/afs/read.d.ts

@@ -3,15 +3,19 @@ import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/
 import { AFSSkillBase } from "./base.js";
 export interface AFSReadInput extends Message {
     path: string;
-    withLineNumbers?: boolean;
+    offset?: number;
+    limit?: number;
 }
 export interface AFSReadOutput extends Message {
     status: string;
     tool: string;
     path: string;
-    withLineNumbers?: boolean;
     data?: AFSEntry;
     message?: string;
+    totalLines?: number;
+    returnedLines?: number;
+    truncated?: boolean;
+    offset?: number;
 }
 export interface AFSReadAgentOptions extends AgentOptions<AFSReadInput, AFSReadOutput> {
     afs: NonNullable<AgentOptions<AFSReadInput, AFSReadOutput>["afs"]>;

package/lib/esm/prompt/skills/afs/read.js

@@ -1,36 +1,50 @@
 import { z } from "zod";
 import { AFSSkillBase } from "./base.js";
+const DEFAULT_LINE_LIMIT = 2000;
+const MAX_LINE_LENGTH = 2000;
 export class AFSReadAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_read",
             description: `Read file contents from the Agentic File System (AFS)
-- Returns the complete content of a file at the specified AFS path
-- Supports line numbers output for precise editing references
-- Use this tool when you need to review, analyze, or understand file content
+- Returns the content of a file at the specified AFS path
+- By default reads up to ${DEFAULT_LINE_LIMIT} lines, use offset/limit for large files
+- Lines longer than ${MAX_LINE_LENGTH} characters will be truncated
 
 Usage:
-- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md", "/memory/user/notes")
-- This is NOT a local system file path - it operates within the AFS virtual file system
-- IMPORTANT: You MUST set withLineNumbers to true before using afs_edit, as line numbers are required for precise edits
-- Returns the file's content along with metadata (id, path, timestamps, etc.)`,
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/readme.md")
+- Use offset to start reading from a specific line (0-based)
+- Use limit to control number of lines returned (default: ${DEFAULT_LINE_LIMIT})
+- Check truncated field to know if file was partially returned`,
             ...options,
             inputSchema: z.object({
                 path: z
                     .string()
                     .describe("Absolute AFS path to the file to read (e.g., '/docs/readme.md'). Must start with '/'"),
-                withLineNumbers: z
-                    .boolean()
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
                     .optional()
-                    .describe("MUST be set to true before using afs_edit. Adds line numbers to output (format: '1| line content')"),
+                    .describe("Line number to start reading from (0-based, default: 0)"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(DEFAULT_LINE_LIMIT)
+                    .optional()
+                    .describe(`Maximum number of lines to read (default: ${DEFAULT_LINE_LIMIT})`),
             }),
             outputSchema: z.object({
                 status: z.string(),
                 tool: z.string(),
                 path: z.string(),
-                withLineNumbers: z.boolean().optional(),
                 data: z.custom().optional(),
                 message: z.string().optional(),
+                totalLines: z.number().optional(),
+                returnedLines: z.number().optional(),
+                truncated: z.boolean().optional(),
+                offset: z.number().optional(),
             }),
         });
     }
@@ -38,22 +52,44 @@ Usage:
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
         const result = await this.afs.read(input.path);
-        let content = result.data?.content;
-        if (input.withLineNumbers && typeof content === "string") {
-            content = content
-                .split("\n")
-                .map((line, idx) => `${idx + 1}| ${line}`)
-                .join("\n");
+        if (!result.data?.content || typeof result.data.content !== "string") {
+            return {
+                status: "success",
+                tool: "afs_read",
+                path: input.path,
+                ...result,
+            };
+        }
+        const offset = input.offset ?? 0;
+        const limit = input.limit ?? DEFAULT_LINE_LIMIT;
+        const allLines = result.data.content.split("\n");
+        const totalLines = allLines.length;
+        // Apply offset and limit
+        const selectedLines = allLines.slice(offset, offset + limit);
+        // Truncate long lines
+        const processedLines = selectedLines.map((line) => line.length > MAX_LINE_LENGTH ? `${line.substring(0, MAX_LINE_LENGTH)}... [truncated]` : line);
+        const returnedLines = processedLines.length;
+        const truncated = offset > 0 || offset + limit < totalLines;
+        const processedContent = processedLines.join("\n");
+        let message;
+        if (truncated) {
+            const startLine = offset + 1;
+            const endLine = offset + returnedLines;
+            message = `Showing lines ${startLine}-${endLine} of ${totalLines}. Use offset/limit to read more.`;
         }
         return {
             status: "success",
             tool: "afs_read",
             path: input.path,
-            withLineNumbers: input.withLineNumbers,
+            totalLines,
+            returnedLines,
+            truncated,
+            offset,
+            message,
             ...result,
-            data: result.data && {
+            data: {
                 ...result.data,
-                content,
+                content: processedContent,
             },
         };
     }

package/lib/esm/prompt/skills/afs/write.js

@@ -40,7 +40,7 @@ Usage:
     async process(input, _options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        const result = await this.afs.write(input.path, {
+        const _result = await this.afs.write(input.path, {
             content: input.content,
         }, {
             append: input.append ?? false,
@@ -49,7 +49,7 @@ Usage:
             status: "success",
             tool: "afs_write",
             path: input.path,
-            ...result,
+            message: "File written successfully",
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.72.0-beta.4",
+  "version": "1.72.0-beta.5",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -93,9 +93,9 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/afs-history": "^1.2.0-beta.3",
-    "@aigne/observability-api": "^0.11.14-beta.1",
     "@aigne/afs": "^1.4.0-beta.3",
+    "@aigne/observability-api": "^0.11.14-beta.1",
+    "@aigne/afs-history": "^1.2.0-beta.3",
     "@aigne/platform-helpers": "^0.6.7-beta"
   },
   "devDependencies": {