@aigne/core 1.71.0 → 1.72.0-beta.10

package/lib/esm/prompt/skills/afs/agent-skill/agent-skill.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { Agent } from "../../../../agents/agent.js";
+const skillToolInputSchema = z.object({
+    skill: z.string().describe("The name of the skill agent to invoke."),
+    args: z.string().optional().describe("The arguments to pass to the skill."),
+});
+export class AgentSkill extends Agent {
+    static formatOutput(output) {
+        if (!("result" in output) || typeof output.result !== "string") {
+            throw new Error("Invalid SkillToolOutput: missing 'result' field");
+        }
+        return output.result;
+    }
+    constructor(options) {
+        super({
+            name: "Skill",
+            taskTitle: "Invoke {{skill}}: {{args}}",
+            ...options,
+            description: `\
+Execute a skill within the main conversation
+
+<skills_instructions>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+When users ask you to run a "slash command" or reference "/" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to invoke the corresponding skill.
+
+User: "run /commit" Assistant: [Calls Skill tool with skill: "commit"]
+How to invoke:
+
+Use this tool with the skill name and optional arguments
+
+Important:
+
+When a skill is relevant, you must invoke this tool IMMEDIATELY as your first action
+NEVER just announce or mention a skill in your text response without actually calling this tool
+This is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
+Only use skills listed in <available_skills> below
+Do not invoke a skill that is already running
+Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
+</skills_instructions>
+
+<available_skills>
+${options.agentSkills.map((s) => `${s.name}: ${s.description}`).join("\n\n")}
+</available_skills>
+`,
+            inputSchema: skillToolInputSchema,
+        });
+        this.agentSkills = options.agentSkills;
+    }
+    agentSkills;
+    async process(input) {
+        const skill = this.agentSkills.find((s) => s.name === input.skill);
+        if (!skill)
+            throw new Error(`Skill not found: ${input.skill}`);
+        return {
+            result: `\
+Base directory for this skill: ${skill.path}
+
+${skill.content}
+
+${input.args ? `ARGUMENTS: ${input.args ?? "None"}` : ""}
+`,
+        };
+    }
+}

package/lib/esm/prompt/skills/afs/agent-skill/skill-loader.d.ts

@@ -0,0 +1,13 @@
+import type { AFS } from "@aigne/afs";
+import { AgentSkill } from "./agent-skill.js";
+export interface Skill {
+    path: string;
+    name: string;
+    description: string;
+    content: string;
+}
+export declare function loadSkill(path: string): Promise<Skill>;
+export declare function loadSkills(paths: string[]): Promise<Skill[]>;
+export declare function loadAgentSkillFromAFS({ afs, }: {
+    afs: AFS;
+}): Promise<AgentSkill | undefined>;

package/lib/esm/prompt/skills/afs/agent-skill/skill-loader.js

@@ -0,0 +1,54 @@
+import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import fm from "front-matter";
+import { AgentSkill } from "./agent-skill.js";
+function parseSkill(content, path) {
+    const meta = fm(content);
+    return {
+        path,
+        name: meta.attributes.name,
+        description: meta.attributes.description,
+        content: meta.body,
+    };
+}
+export async function loadSkill(path) {
+    const entry = nodejs.path.join(path, "SKILL.md");
+    const skill = await nodejs.fs.readFile(entry, "utf-8");
+    return parseSkill(skill, path);
+}
+export async function loadSkills(paths) {
+    const skills = [];
+    for (const path of paths) {
+        const skill = await loadSkill(path);
+        skills.push(skill);
+    }
+    return skills;
+}
+export async function loadAgentSkillFromAFS({ afs, }) {
+    const modules = await afs.listModules();
+    const filtered = modules.filter(({ module: m }) => "options" in m &&
+        typeof m.options === "object" &&
+        m.options &&
+        "agentSkills" in m.options &&
+        m.options.agentSkills === true);
+    if (!filtered.length)
+        return;
+    const skills = [];
+    for (const module of filtered) {
+        const data = (await afs.list(module.path, {
+            pattern: "**/SKILL.md",
+            maxDepth: 10,
+        })).data;
+        for (const entry of data) {
+            const { data: file } = await afs.read(entry.path);
+            if (typeof file?.content !== "string")
+                continue;
+            const skill = parseSkill(file.content, nodejs.path.dirname(entry.path));
+            skills.push(skill);
+        }
+    }
+    if (!skills.length)
+        return;
+    return new AgentSkill({
+        agentSkills: skills,
+    });
+}

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

@@ -0,0 +1,4 @@
+import { Agent, type Message } from "../../../agents/agent.js";
+export declare abstract class AFSSkillBase<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    tag: string;
+}

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

@@ -0,0 +1,4 @@
+import { Agent } from "../../../agents/agent.js";
+export class AFSSkillBase extends Agent {
+    tag = "AFS";
+}

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

@@ -1,4 +1,5 @@
-import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "../../../agents/agent.js";
+import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
+import { AFSSkillBase } from "./base.js";
 export interface AFSDeleteInput extends Message {
     path: string;
     recursive?: boolean;
@@ -12,7 +13,7 @@ export interface AFSDeleteOutput extends Message {
 export interface AFSDeleteAgentOptions extends AgentOptions<AFSDeleteInput, AFSDeleteOutput> {
     afs: NonNullable<AgentOptions<AFSDeleteInput, AFSDeleteOutput>["afs"]>;
 }
-export declare class AFSDeleteAgent extends Agent<AFSDeleteInput, AFSDeleteOutput> {
+export declare class AFSDeleteAgent extends AFSSkillBase<AFSDeleteInput, AFSDeleteOutput> {
     constructor(options: AFSDeleteAgentOptions);
     process(input: AFSDeleteInput, _options: AgentInvokeOptions): Promise<AFSDeleteOutput>;
 }

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

@@ -1,18 +1,30 @@
 import { z } from "zod";
-import { Agent, } from "../../../agents/agent.js";
-export class AFSDeleteAgent extends Agent {
+import { AFSSkillBase } from "./base.js";
+export class AFSDeleteAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_delete",
-            description: "Permanently delete files or directories. Use when removing unwanted files or cleaning up temporary data.",
+            description: `Permanently delete files or directories from the Agentic File System (AFS)
+- Removes files or directories at the specified AFS path
+- Supports recursive deletion for directories with contents
+- Use with caution as deletion is permanent
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/old-file.md", "/temp")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- To delete a directory, you MUST set recursive=true
+- Deleting a non-empty directory without recursive=true will fail
+- This operation cannot be undone`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file or directory path to delete"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to delete (e.g., '/docs/old-file.md', '/temp'). Must start with '/'"),
                 recursive: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Allow directory deletion (default: false, required for directories)"),
+                    .describe("MUST be set to true to delete directories. Default: false (files only)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

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

@@ -1,26 +1,24 @@
-import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "../../../agents/agent.js";
-export interface Patch {
-    start_line: number;
-    end_line: number;
-    replace?: string;
-    delete: boolean;
-}
+import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
+import { AFSSkillBase } from "./base.js";
 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;
-    content: string;
+    snippet: string;
 }
 export interface AFSEditAgentOptions extends AgentOptions<AFSEditInput, AFSEditOutput> {
     afs: NonNullable<AgentOptions<AFSEditInput, AFSEditOutput>["afs"]>;
 }
-export declare class AFSEditAgent extends Agent<AFSEditInput, AFSEditOutput> {
+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,94 +1,120 @@
 import { z } from "zod";
-import { Agent, } from "../../../agents/agent.js";
-export class AFSEditAgent extends Agent {
+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 file content. Use when making targeted changes without rewriting the entire file.",
+            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")
+- 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 file path to edit"),
-                patches: z
-                    .array(z.object({
-                    start_line: z.number().int().describe("Start line number (0-based, inclusive)"),
-                    end_line: z.number().int().describe("End line number (0-based, exclusive)"),
-                    replace: z.string().optional().describe("New content to replace the line range"),
-                    delete: z.boolean().describe("Delete mode: true to delete lines, false to replace"),
-                }))
-                    .min(1)
-                    .describe("List of patches to apply sequentially"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the file to edit (e.g., '/docs/readme.md'). Must start with '/'"),
+                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(),
-                content: 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);
-        if (!readResult.result?.content || typeof readResult.result.content !== "string") {
-            throw new Error(`Cannot read file content from: ${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: ${path}`);
         }
-        const originalContent = readResult.result.content;
-        const updatedContent = this.applyCustomPatches(originalContent, input.patches);
-        await this.afs.write(input.path, {
+        const originalContent = readResult.data.content;
+        // 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}`,
-            content: 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/exec.d.ts

@@ -1,15 +1,16 @@
-import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "../../../agents/agent.js";
+import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
+import { AFSSkillBase } from "./base.js";
 export interface AFSExecInput extends Message {
     path: string;
     args: string;
 }
 export interface AFSExecOutput extends Message {
-    result: Record<string, any>;
+    data: Record<string, any>;
 }
 export interface AFSExecAgentOptions extends AgentOptions<AFSExecInput, AFSExecOutput> {
     afs: NonNullable<AgentOptions<AFSExecInput, AFSExecOutput>["afs"]>;
 }
-export declare class AFSExecAgent extends Agent<AFSExecInput, AFSExecOutput> {
+export declare class AFSExecAgent extends AFSSkillBase<AFSExecInput, AFSExecOutput> {
     constructor(options: AFSExecAgentOptions);
     process(input: AFSExecInput, options: AgentInvokeOptions): Promise<AFSExecOutput>;
 }

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

@@ -1,23 +1,39 @@
 import { z } from "zod";
-import { Agent, } from "../../../agents/agent.js";
-export class AFSExecAgent extends Agent {
+import { AFSSkillBase } from "./base.js";
+export class AFSExecAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_exec",
-            description: "Execute functions or commands from AFS modules. Use when running operations provided by mounted modules.",
+            description: `Execute files marked as executable in the Agentic File System (AFS)
+- Runs executable entries (functions, agents, skills) registered at a given AFS path
+- Passes arguments to the executable and returns its output
+- Use this to invoke dynamic functionality stored in AFS
+
+Usage:
+- The path must be an absolute AFS path to an executable entry (e.g., "/skills/summarize", "/agents/translator")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- Use afs_list to discover available executables (look for entries with execute metadata)
+- Arguments must be a valid JSON string matching the executable's input schema
+- The executable's input/output schema can be found in its metadata`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute path to the executable function in AFS"),
-                args: z.string().describe("JSON string of arguments matching the function's input schema"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the executable (e.g., '/skills/summarize'). Must start with '/'"),
+                args: z
+                    .string()
+                    .describe('JSON string of arguments matching the executable\'s input schema (e.g., \'{"text": "hello"}\')'),
             }),
             outputSchema: z.object({
-                result: z.record(z.any()),
+                data: z.record(z.any()),
             }),
         });
     }
     async process(input, options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        return await this.afs.exec(input.path, JSON.parse(input.args), options);
+        return {
+            ...(await this.afs.exec(input.path, JSON.parse(input.args), options)),
+        };
     }
 }

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

@@ -1,3 +1,5 @@
+import { isNonNullable } from "../../../utils/type-utils.js";
+import { loadAgentSkillFromAFS } from "./agent-skill/skill-loader.js";
 import { AFSDeleteAgent } from "./delete.js";
 import { AFSEditAgent } from "./edit.js";
 import { AFSExecAgent } from "./exec.js";
@@ -16,5 +18,6 @@ export async function getAFSSkills(afs) {
         new AFSDeleteAgent({ afs }),
         new AFSRenameAgent({ afs }),
         new AFSExecAgent({ afs }),
-    ];
+        await loadAgentSkillFromAFS({ afs }),
+    ].filter(isNonNullable);
 }

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

@@ -1,5 +1,6 @@
 import type { AFSListOptions } from "@aigne/afs";
-import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "../../../agents/agent.js";
+import type { AgentInvokeOptions, AgentOptions, Message } from "../../../agents/agent.js";
+import { AFSSkillBase } from "./base.js";
 export interface AFSListInput extends Message {
     path: string;
     options?: AFSListOptions;
@@ -10,13 +11,12 @@ export interface AFSListOutput extends Message {
     path: string;
     options?: AFSListOptions;
     message?: string;
-    result: string;
+    data?: unknown;
 }
 export interface AFSListAgentOptions extends AgentOptions<AFSListInput, AFSListOutput> {
     afs: NonNullable<AgentOptions<AFSListInput, AFSListOutput>["afs"]>;
 }
-export declare class AFSListAgent extends Agent<AFSListInput, AFSListOutput> {
+export declare class AFSListAgent extends AFSSkillBase<AFSListInput, AFSListOutput> {
     constructor(options: AFSListAgentOptions);
     process(input: AFSListInput, _options: AgentInvokeOptions): Promise<AFSListOutput>;
-    private buildTreeView;
 }