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

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

@@ -7,14 +7,25 @@ class AFSExecAgent extends base_js_1.AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_exec",
-            description: `
-Execute files marked as executable in the Agentic File System (AFS).
-Use this to run executable files registered at a given path with specified arguments.
-      `.trim(),
+            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: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute path to the executable file in AFS"),
-                args: zod_1.z.string().describe("JSON string of arguments matching the function's input schema"),
+                path: zod_1.z
+                    .string()
+                    .describe("Absolute AFS path to the executable (e.g., '/skills/summarize'). Must start with '/'"),
+                args: zod_1.z
+                    .string()
+                    .describe('JSON string of arguments matching the executable\'s input schema (e.g., \'{"text": "hello"}\')'),
             }),
             outputSchema: zod_1.z.object({
                 data: zod_1.z.record(zod_1.z.any()),

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAFSSkills = getAFSSkills;
+const type_utils_js_1 = require("../../../utils/type-utils.js");
+const skill_loader_js_1 = require("./agent-skill/skill-loader.js");
 const delete_js_1 = require("./delete.js");
 const edit_js_1 = require("./edit.js");
 const exec_js_1 = require("./exec.js");
@@ -19,5 +21,6 @@ async function getAFSSkills(afs) {
         new delete_js_1.AFSDeleteAgent({ afs }),
         new rename_js_1.AFSRenameAgent({ afs }),
         new exec_js_1.AFSExecAgent({ afs }),
-    ];
+        await (0, skill_loader_js_1.loadAgentSkillFromAFS)({ afs }),
+    ].filter(type_utils_js_1.isNonNullable);
 }

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

@@ -7,26 +7,42 @@ class AFSListAgent extends base_js_1.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: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute directory path to browse"),
+                path: zod_1.z
+                    .string()
+                    .describe("Absolute AFS path to list (e.g., '/', '/docs', '/memory/user'). Must start with '/'"),
                 options: zod_1.z
                     .object({
-                    maxDepth: zod_1.z.number().optional().describe("Tree depth limit (default: 1)"),
+                    maxDepth: zod_1.z
+                        .number()
+                        .optional()
+                        .describe("Maximum depth of directory recursion. 1 = current directory only, 2 = include subdirectories, etc. Default: 1"),
                     disableGitignore: zod_1.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: zod_1.z
                         .number()
                         .optional()
-                        .describe("Maximum number of children to list per directory"),
-                    format: zod_1.z
-                        .union([zod_1.z.literal("simple-list"), zod_1.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: zod_1.z.string().optional().describe("Glob pattern to filter entries by path"),
                 })
                     .optional(),
             }),

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

@@ -7,14 +7,25 @@ class AFSReadAgent extends base_js_1.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: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute file path to read"),
+                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()
                     .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: zod_1.z.object({
                 status: zod_1.z.string(),

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

@@ -7,16 +7,30 @@ class AFSRenameAgent extends base_js_1.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: zod_1.z.object({
-                oldPath: zod_1.z.string().describe("Absolute current file or directory path"),
-                newPath: zod_1.z.string().describe("Absolute new file or directory path"),
+                oldPath: zod_1.z
+                    .string()
+                    .describe("Current absolute AFS path (e.g., '/docs/old-name.md'). Must start with '/'"),
+                newPath: zod_1.z
+                    .string()
+                    .describe("New absolute AFS path (e.g., '/docs/new-name.md'). Must start with '/'"),
                 overwrite: zod_1.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: zod_1.z.object({
                 status: zod_1.z.string(),

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

@@ -7,18 +7,34 @@ class AFSSearchAgent extends base_js_1.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: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute directory path to search in"),
-                query: zod_1.z.string().describe("Search keywords or patterns"),
+                path: zod_1.z
+                    .string()
+                    .describe("Absolute AFS path to search in (e.g., '/', '/docs', '/memory'). Must start with '/'"),
+                query: zod_1.z.string().describe("Text, keywords, or patterns to search for in file contents"),
                 options: zod_1.z
                     .object({
-                    limit: zod_1.z.number().optional().describe("Max results to return"),
+                    limit: zod_1.z
+                        .number()
+                        .optional()
+                        .describe("Maximum number of results to return. Useful for limiting output size"),
                     caseSensitive: zod_1.z
                         .boolean()
                         .optional()
-                        .describe("Case-sensitive search (default: false)"),
+                        .describe("Set to true for case-sensitive matching. Default: false (case-insensitive)"),
                 })
                     .optional(),
             }),

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

@@ -7,16 +7,30 @@ class AFSWriteAgent extends base_js_1.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: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute file path to write"),
-                content: zod_1.z.string().describe("Complete file content or content to append"),
+                path: zod_1.z
+                    .string()
+                    .describe("Absolute AFS path for the file to write (e.g., '/docs/new-file.md'). Must start with '/'"),
+                content: zod_1.z
+                    .string()
+                    .describe("The content to write to the file. In overwrite mode, this replaces the entire file"),
                 append: zod_1.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: zod_1.z.object({
                 status: zod_1.z.string(),

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

@@ -27,35 +27,38 @@ export declare class ChatMessageTemplate {
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     options?: FormatOptions | undefined;
-    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
+    cacheControl?: ChatModelInputMessage["cacheControl"];
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): UserMessageTemplate;
 }
 export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
-    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
-    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
+    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;
     }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
-    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
-    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
+    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;
     }>;
 }
 export declare class ChatMessagesTemplate {
@@ -69,25 +72,61 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: z.ZodLiteral<"system">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "system";
     content: string;
+    role: "system";
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }, {
-    role: "system";
     content: string;
+    role: "system";
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"user">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "user";
     content: string;
+    role: "user";
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }, {
-    role: "user";
     content: string;
+    role: "user";
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"agent">;
@@ -121,10 +160,23 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         id: string;
     }>, "many">>;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "agent";
-    name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -133,10 +185,14 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | undefined;
+    name?: string | undefined;
 }, {
     role: "agent";
-    name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -145,20 +201,39 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         type: "function";
         id: string;
     }[] | 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>>;
     toolCallId: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    role: "tool";
     content: string;
+    role: "tool";
     toolCallId: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }, {
-    role: "tool";
     content: string | Record<string, unknown>;
+    role: "tool";
     toolCallId: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     name?: string | undefined;
 }>]>;
 export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

package/lib/cjs/prompt/template.js

@@ -80,11 +80,13 @@ class ChatMessageTemplate {
     content;
     name;
     options;
-    constructor(role, content, name, options) {
+    cacheControl;
+    constructor(role, content, name, options, cacheControl) {
         this.role = role;
         this.content = content;
         this.name = name;
         this.options = options;
+        this.cacheControl = cacheControl;
     }
     async format(variables, options) {
         options = { ...this.options, ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)) };
@@ -103,29 +105,30 @@ class ChatMessageTemplate {
             role: this.role,
             content,
             name: this.name,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.ChatMessageTemplate = ChatMessageTemplate;
 class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content, name, options) {
-        return new SystemMessageTemplate("system", content, name, options);
+    static from(content, name, options, cacheControl) {
+        return new SystemMessageTemplate("system", content, name, options, cacheControl);
     }
 }
 exports.SystemMessageTemplate = SystemMessageTemplate;
 class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template, name, options) {
-        return new UserMessageTemplate("user", template, name, options);
+    static from(template, name, options, cacheControl) {
+        return new UserMessageTemplate("user", template, name, options, cacheControl);
     }
 }
 exports.UserMessageTemplate = UserMessageTemplate;
 class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls;
-    static from(template, toolCalls, name, options) {
-        return new AgentMessageTemplate(template, toolCalls, name, options);
+    static from(template, toolCalls, name, options, cacheControl) {
+        return new AgentMessageTemplate(template, toolCalls, name, options, cacheControl);
     }
-    constructor(content, toolCalls, name, options) {
-        super("agent", content, name, options);
+    constructor(content, toolCalls, name, options, cacheControl) {
+        super("agent", content, name, options, cacheControl);
         this.toolCalls = toolCalls;
     }
     async format(_variables, _options) {
@@ -135,17 +138,18 @@ class AgentMessageTemplate extends ChatMessageTemplate {
             // NOTE: agent message should not rendered by template
             content: this.content,
             toolCalls: this.toolCalls,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.AgentMessageTemplate = AgentMessageTemplate;
 class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId;
-    static from(content, toolCallId, name, options) {
-        return new ToolMessageTemplate(content, toolCallId, name, options);
+    static from(content, toolCallId, name, options, cacheControl) {
+        return new ToolMessageTemplate(content, toolCallId, name, options, cacheControl);
     }
-    constructor(content, toolCallId, name, options) {
-        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options);
+    constructor(content, toolCallId, name, options, cacheControl) {
+        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options, cacheControl);
         this.toolCallId = toolCallId;
     }
     async format(_variables, _options) {
@@ -155,6 +159,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
             // NOTE: tool result should not rendered by template
             content: this.content,
             toolCallId: this.toolCallId,
+            cacheControl: this.cacheControl,
         };
     }
 }
@@ -179,11 +184,23 @@ const systemChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("system"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const userChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("user"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatModelOutputToolCallSchema = zod_1.z.object({
     id: zod_1.z.string(),
@@ -198,6 +215,12 @@ const agentChatMessageSchema = zod_1.z.object({
     content: zod_1.z.string().optional(),
     toolCalls: zod_1.z.array(chatModelOutputToolCallSchema).optional(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const toolChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("tool"),
@@ -206,6 +229,12 @@ const toolChatMessageSchema = zod_1.z.object({
         .transform((val) => (typeof val !== "string" ? JSON.stringify(val) : val)),
     toolCallId: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatMessageSchema = zod_1.z.union([
     systemChatMessageSchema,
@@ -224,13 +253,13 @@ function parseChatMessages(messages) {
     return messages.map((message) => {
         switch (message.role) {
             case "system":
-                return SystemMessageTemplate.from(message.content, message.name, message.options);
+                return SystemMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "user":
-                return UserMessageTemplate.from(message.content, message.name, message.options);
+                return UserMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "agent":
-                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options);
+                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options, message.cacheControl);
             case "tool":
-                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options);
+                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options, message.cacheControl);
         }
     });
 }

package/lib/dts/agents/agent.d.ts

@@ -1,7 +1,7 @@
 import { AFS, type AFSExecOptions, type AFSExecResult, type AFSListOptions, type AFSListResult, type AFSModule, type AFSOptions, type AFSReadResult, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
-import { type ZodObject, type ZodType } from "zod";
+import { type ZodObject, type ZodType, z } from "zod";
 import type { AgentEvent, Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
 import type { ContextUsage } from "../aigne/usage.js";
@@ -783,6 +783,25 @@ export interface AgentResponseProgress {
     } | {
         event: "agentFailed";
         error: Error;
+    } | {
+        event: "message";
+        role: "user" | "agent";
+        message: ({
+            type: "text";
+            content: string;
+        } | {
+            type: "thinking";
+            thoughts: string;
+        } | {
+            type: "tool_use";
+            toolUseId: string;
+            name: string;
+            input: unknown;
+        } | {
+            type: "tool_result";
+            toolUseId: string;
+            content: unknown;
+        })[];
     }) & Omit<AgentEvent, "agent"> & {
         agent: {
             name: string;
@@ -870,6 +889,17 @@ export interface FunctionAgentOptions<I extends Message = Message, O extends Mes
  */
 export declare class FunctionAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     tag: string;
+    static schema(): ZodObject<{
+        process: ZodType<FunctionAgentFn>;
+    }, "strip", z.ZodTypeAny, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     /**
      * Create a function agent from a function or options
      *