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

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.js

@@ -4,26 +4,42 @@ export class AFSListAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_list",
-            description: "Browse directory structure as a tree view. Use when exploring directory contents or understanding file organization.",
+            description: `List contents within the Agentic File System (AFS)
+- Returns files and directories at the specified AFS path
+- Supports recursive listing with configurable depth
+- Supports glob pattern filtering to match specific files
+- By default respects .gitignore rules to filter out ignored files
+- Use this tool when you need to explore AFS contents or understand file organization
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/", "/docs", "/memory/user")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- Use maxDepth to control recursion depth (default: 1, current directory only)
+- Use pattern to filter entries by glob pattern:
+  - "*.ts" - match TypeScript files in current directory
+  - "**/*.js" - match all JavaScript files recursively
+  - "src/**/*.{ts,tsx}" - match TypeScript files in src directory
+- Results are filtered by .gitignore by default; set disableGitignore to include ignored files`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute directory path to browse"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to list (e.g., '/', '/docs', '/memory/user'). Must start with '/'"),
                 options: z
                     .object({
-                    maxDepth: z.number().optional().describe("Tree depth limit (default: 1)"),
+                    maxDepth: z
+                        .number()
+                        .optional()
+                        .describe("Maximum depth of directory recursion. 1 = current directory only, 2 = include subdirectories, etc. Default: 1"),
                     disableGitignore: z
                         .boolean()
                         .optional()
-                        .describe("Disable .gitignore filtering, default is enabled"),
+                        .describe("Set to true to include files normally ignored by .gitignore rules. Default: false (respects .gitignore)"),
                     maxChildren: z
                         .number()
                         .optional()
-                        .describe("Maximum number of children to list per directory"),
-                    format: z
-                        .union([z.literal("simple-list"), z.literal("tree")])
-                        .optional()
-                        .default("simple-list")
-                        .describe("Output format, either 'simple-list', or 'tree', default is 'simple-list'"),
+                        .describe("Maximum number of entries to return per directory. Useful for large directories to avoid overwhelming output"),
+                    pattern: z.string().optional().describe("Glob pattern to filter entries by path"),
                 })
                     .optional(),
             }),

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

@@ -4,14 +4,25 @@ export class AFSReadAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_read",
-            description: "Read complete file contents. Use when you need to review, analyze, or understand file content before making changes.",
+            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
+
+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.)`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file path to read"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to the file to read (e.g., '/docs/readme.md'). Must start with '/'"),
                 withLineNumbers: z
                     .boolean()
                     .optional()
-                    .describe("Include line numbers in output (required when planning to edit the file)"),
+                    .describe("MUST be set to true before using afs_edit. Adds line numbers to output (format: '1| line content')"),
             }),
             outputSchema: z.object({
                 status: z.string(),

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

@@ -4,16 +4,30 @@ export class AFSRenameAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_rename",
-            description: "Rename or move files and directories. Use when reorganizing files, changing names, or moving to different locations.",
+            description: `Rename or move files and directories within the Agentic File System (AFS)
+- Renames a file or directory to a new name
+- Can also move files/directories to a different location
+- Optionally overwrites existing files at the destination
+
+Usage:
+- Both paths must be absolute AFS paths starting with "/" (e.g., "/docs/old-name.md" -> "/docs/new-name.md")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- To move a file, specify a different directory in newPath (e.g., "/docs/file.md" -> "/archive/file.md")
+- If newPath already exists, the operation will fail unless overwrite=true
+- Moving directories moves all contents recursively`,
             ...options,
             inputSchema: z.object({
-                oldPath: z.string().describe("Absolute current file or directory path"),
-                newPath: z.string().describe("Absolute new file or directory path"),
+                oldPath: z
+                    .string()
+                    .describe("Current absolute AFS path (e.g., '/docs/old-name.md'). Must start with '/'"),
+                newPath: z
+                    .string()
+                    .describe("New absolute AFS path (e.g., '/docs/new-name.md'). Must start with '/'"),
                 overwrite: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Overwrite if destination exists (default: false)"),
+                    .describe("Set to true to overwrite if destination already exists. Default: false (fails if exists)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

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

@@ -4,18 +4,34 @@ export class AFSSearchAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_search",
-            description: "Search file contents by keywords. Use when finding files containing specific text or code patterns.",
+            description: `Search file contents within the Agentic File System (AFS)
+- Searches for files containing specific text, keywords, or patterns
+- Returns matching entries with their content and metadata
+- Supports case-sensitive and case-insensitive search modes
+- Use this tool when you need to find files by their content
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/", "/docs", "/memory")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- The query can be keywords, phrases, or text patterns to search for
+- Use limit to control the number of results returned
+- Search is case-insensitive by default; set caseSensitive to true for exact case matching`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute directory path to search in"),
-                query: z.string().describe("Search keywords or patterns"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path to search in (e.g., '/', '/docs', '/memory'). Must start with '/'"),
+                query: z.string().describe("Text, keywords, or patterns to search for in file contents"),
                 options: z
                     .object({
-                    limit: z.number().optional().describe("Max results to return"),
+                    limit: z
+                        .number()
+                        .optional()
+                        .describe("Maximum number of results to return. Useful for limiting output size"),
                     caseSensitive: z
                         .boolean()
                         .optional()
-                        .describe("Case-sensitive search (default: false)"),
+                        .describe("Set to true for case-sensitive matching. Default: false (case-insensitive)"),
                 })
                     .optional(),
             }),

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

@@ -4,16 +4,30 @@ export class AFSWriteAgent extends AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_write",
-            description: "Create new file or append content to existing file. Use when creating files, rewriting entire files, or appending to files.",
+            description: `Write or create files in the Agentic File System (AFS)
+- Creates a new file or overwrites an existing file with the provided content
+- Supports append mode to add content to the end of existing files
+- Use this tool when creating new files or completely replacing file contents
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/new-file.md", "/memory/user/notes")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- By default, this tool overwrites the entire file content
+- Use append mode to add content to the end of an existing file without replacing it
+- For partial edits to existing files, prefer using afs_edit instead`,
             ...options,
             inputSchema: z.object({
-                path: z.string().describe("Absolute file path to write"),
-                content: z.string().describe("Complete file content or content to append"),
+                path: z
+                    .string()
+                    .describe("Absolute AFS path for the file to write (e.g., '/docs/new-file.md'). Must start with '/'"),
+                content: z
+                    .string()
+                    .describe("The content to write to the file. In overwrite mode, this replaces the entire file"),
                 append: z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Append mode: add content to end of file (default: false, overwrites file)"),
+                    .describe("Set to true to append content to the end of an existing file. Default: false (overwrites entire file)"),
             }),
             outputSchema: z.object({
                 status: z.string(),

package/lib/esm/prompt/template.d.ts

@@ -42,11 +42,11 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "system" | "user" | "agent" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCalls: ChatModelOutputToolCall[] | undefined;
-        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
+        cacheControl: import("../index.js").CacheControl | undefined;
     }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
@@ -54,11 +54,11 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
     static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "system" | "user" | "agent" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCallId: string;
-        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
+        cacheControl: import("../index.js").CacheControl | undefined;
     }>;
 }
 export declare class ChatMessagesTemplate {
@@ -83,21 +83,21 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         ttl?: "5m" | "1h" | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "system";
     content: string;
-    name?: string | undefined;
+    role: "system";
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }, {
-    role: "system";
     content: string;
-    name?: string | undefined;
+    role: "system";
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"user">;
     content: z.ZodString;
@@ -113,21 +113,21 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         ttl?: "5m" | "1h" | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "user";
     content: string;
-    name?: string | undefined;
+    role: "user";
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }, {
-    role: "user";
     content: string;
-    name?: string | undefined;
+    role: "user";
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"agent">;
     content: z.ZodOptional<z.ZodString>;
@@ -172,8 +172,11 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     role: "agent";
-    name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -182,14 +185,14 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | undefined;
+    name?: string | undefined;
+}, {
+    role: "agent";
+    content?: string | undefined;
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
-}, {
-    role: "agent";
-    name?: string | undefined;
-    content?: string | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -198,10 +201,7 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | undefined;
-    cacheControl?: {
-        type: "ephemeral";
-        ttl?: "5m" | "1h" | undefined;
-    } | undefined;
+    name?: string | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"tool">;
     content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
@@ -218,23 +218,23 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         ttl?: "5m" | "1h" | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "tool";
     content: string;
+    role: "tool";
     toolCallId: string;
-    name?: string | undefined;
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }, {
-    role: "tool";
     content: string | Record<string, unknown>;
+    role: "tool";
     toolCallId: string;
-    name?: string | undefined;
     cacheControl?: {
         type: "ephemeral";
         ttl?: "5m" | "1h" | undefined;
     } | undefined;
+    name?: string | undefined;
 }>]>;
 export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
 export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.72.0-beta.3",
+  "version": "1.72.0-beta.4",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -78,6 +78,7 @@
     "debug": "^4.4.3",
     "eventsource-parser": "^3.0.6",
     "fast-deep-equal": "^3.1.3",
+    "front-matter": "^4.0.2",
     "immer": "^10.1.3",
     "is-network-error": "^1.2.0",
     "jaison": "^2.0.2",
@@ -92,10 +93,10 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/afs": "^1.4.0-beta.2",
-    "@aigne/platform-helpers": "^0.6.7-beta",
+    "@aigne/afs-history": "^1.2.0-beta.3",
     "@aigne/observability-api": "^0.11.14-beta.1",
-    "@aigne/afs-history": "^1.2.0-beta.2"
+    "@aigne/afs": "^1.4.0-beta.3",
+    "@aigne/platform-helpers": "^0.6.7-beta"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",