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

package/lib/esm/prompt/compact/user-memory-extractor.js

@@ -0,0 +1,120 @@
+import { optional, z } from "zod";
+import { AIAgent } from "../../agents/ai-agent.js";
+import { isNil, omitBy } from "../../utils/type-utils.js";
+const EXTRACTOR_INSTRUCTIONS = `\
+You are a user memory extractor. Your task is to extract long-term user memory facts from session memory that represent verified, persistent user characteristics.
+
+## Session Memory Facts (from current session)
+
+${"```"}yaml alt="session-facts"
+{{ sessionFacts | yaml.stringify }}
+${"```"}
+
+## Existing User Memory Facts
+
+${"```"}yaml alt="existing-user-facts"
+{{ existingUserFacts | yaml.stringify }}
+${"```"}
+
+## Guidelines
+
+1. **Extract session facts into long-term user memory**:
+   - Promote facts that represent lasting user characteristics (preferences, skills, working style)
+   - Filter out temporary or session-specific information
+   - Aggregate patterns observed across multiple sessions
+   - Verify consistency with existing user memory
+
+2. **User memory should focus on USER characteristics**:
+   - **Preferences**: Lasting tool/framework/language preferences the user likes to use
+   - **Skills**: Confirmed technical expertise and proficiency levels of the user
+   - **Working style**: User's communication preferences, workflow patterns, coding standards
+   - **Personal context**: Stable personal context (timezone, team structure, role, work hours)
+   - **Project basic info**: What projects the user is working on and their role in them
+     - Example: "User is building an AI Agent framework called aigne-framework"
+     - Example: "User is the tech lead on a React e-commerce project"
+     - DO NOT include project technical details, architecture, or implementation specifics
+
+3. **DO NOT include in user memory**:
+   - Session-specific tasks or temporary goals
+   - Bugs or issues being debugged in a specific session
+   - One-time decisions or experimental choices
+   - Unverified assumptions or single-instance observations
+   - **Project technical details**: architecture decisions, tech stack specifics, implementation details
+   - **Project problems**: current bugs, issues, technical debt, or temporary blockers
+   - Information about the codebase structure or specific files/modules
+
+4. **Output only changes (CRITICAL)**:
+   - Only output facts that need to be added or updated
+   - DO NOT output facts that already exist and don't need changes
+   - Each label in newFacts must be unique
+   - When a label already exists in user memory:
+     - Include it in newFacts ONLY if session provides new information to update it
+     - Omit it from newFacts if it doesn't need changes
+   - Use the same label format as session memory: "pref-*", "skill-*", "proj-*", "ctx-*"
+
+5. **When to output a fact in newFacts**:
+   - **New fact**: Extracting a brand new user characteristic not in existing user memory
+   - **Updated fact**: Session provides new information that enhances an existing fact
+   - **Refined fact**: Multiple sessions show patterns that refine existing facts
+   - DO NOT output if: The fact already exists and session doesn't add new information
+
+6. **When to remove facts** (add labels to removeFacts):
+   - Facts are proven to be outdated or incorrect
+   - User explicitly changed their approach permanently
+   - Facts are redundant with newer, better facts
+
+7. **Confidence scoring**:
+   - Higher confidence (0.8-1.0): Verified across multiple sessions or explicitly stated
+   - Medium confidence (0.5-0.7): Observed patterns but limited data
+   - Lower confidence (0.3-0.4): Tentative patterns, may need more verification
+   - Below 0.3: Don't extract into user memory yet
+
+8. **Extraction criteria**:
+   - Only extract facts that are clearly valuable long-term
+   - Prefer quality over quantity - fewer high-confidence facts are better
+   - When in doubt, wait for more sessions to verify the pattern
+
+Output the extracted user memory facts and any facts to remove.`;
+export class AIUserMemoryExtractor extends AIAgent {
+    constructor(options) {
+        super({
+            name: "UserMemoryExtractor",
+            description: "Extracts long-term user memory facts from session memory",
+            inputSchema: z.object({
+                sessionFacts: z
+                    .array(z.object({
+                    label: z.string(),
+                    fact: z.string(),
+                    confidence: optional(z.number()),
+                    tags: optional(z.array(z.string())),
+                }))
+                    .describe("Session memory facts to extract from"),
+                existingUserFacts: optional(z
+                    .array(z.object({
+                    label: z.string(),
+                    fact: z.string(),
+                    confidence: optional(z.number()),
+                    tags: optional(z.array(z.string())),
+                }))
+                    .describe("Existing user memory facts for context and deduplication")),
+            }),
+            outputSchema: z.object({
+                newFacts: z
+                    .array(z.object({
+                    label: z.string().describe("Short, semantic label for the fact (must be unique)"),
+                    fact: z.string().describe("The extracted fact content"),
+                    confidence: optional(z.number().min(0).max(1).describe("Confidence score (0-1)")),
+                    tags: optional(z.array(z.string()).describe("Classification tags")),
+                }))
+                    .describe("Facts to add or update in user memory. Only include facts that are new or need updates. Do not include unchanged facts."),
+                removeFacts: optional(z.array(z.string()).describe("Labels of facts to remove from user memory")),
+            }),
+            instructions: EXTRACTOR_INSTRUCTIONS,
+            taskRenderMode: "hide",
+            ...omitBy(options ?? {}, (v) => isNil(v)),
+            session: {
+                mode: "disabled",
+            },
+        });
+    }
+}

package/lib/esm/prompt/context/afs/history.d.ts

@@ -1,5 +1,9 @@
+import type { AFSListOptions } from "@aigne/afs";
 import type { Agent } from "../../../agents/agent.js";
-export declare function getHistories(agent: Agent): Promise<{
+export declare function getHistories({ filter, agent, }: {
+    filter: AFSListOptions["filter"];
+    agent: Agent;
+}): Promise<{
     role: "user" | "agent";
     content: unknown;
 }[]>;

package/lib/esm/prompt/context/afs/history.js

@@ -1,6 +1,6 @@
 import { AFSHistory } from "@aigne/afs-history";
 import { isNonNullable } from "../../../utils/type-utils.js";
-export async function getHistories(agent) {
+export async function getHistories({ filter, agent, }) {
     const afs = agent?.afs;
     if (!afs)
         return [];
@@ -8,7 +8,8 @@ export async function getHistories(agent) {
     if (!historyModule)
         return [];
     const history = (await afs.list(historyModule.path, {
-        limit: agent.historyConfig?.maxItems || 10,
+        filter,
+        limit: 10,
         orderBy: [["createdAt", "desc"]],
     })).data;
     return history

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

@@ -17,7 +17,14 @@ export function createAFSContext(agent, context) {
         get histories() {
             if (!agent)
                 return Promise.resolve([]);
-            return getHistories(agent);
+            return getHistories({
+                agent,
+                filter: {
+                    agentId: agent.name,
+                    userId: context?.userContext.userId,
+                    sessionId: context?.userContext.sessionId,
+                },
+            });
         },
         get skills() {
             const afs = agent?.afs;

package/lib/esm/prompt/prompt-builder.d.ts

@@ -1,14 +1,17 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
+import { Agent, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
-import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import type { ChatModel, ChatModelInput, ChatModelInputMessage } from "../agents/chat-model.js";
 import { type FileUnionContent } from "../agents/model.js";
+import type { Context } from "../aigne/context.js";
+import { AgentSession } from "./agent-session.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
 }
-export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
+export interface PromptBuildOptions {
+    context?: Context;
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -26,7 +29,9 @@ export declare class PromptBuilder {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
     copy(): PromptBuilder;
-    build(options: PromptBuildOptions): Promise<ChatModelInput & {
+    build(options: PromptBuildOptions): Promise<Omit<ChatModelInput, "messages"> & {
+        session: AgentSession;
+        userMessage: ChatModelInputMessage;
         toolAgents?: Agent[];
     }>;
     buildPrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
@@ -37,11 +42,8 @@ export declare class PromptBuilder {
     }>;
     private getTemplateVariables;
     private buildMessages;
-    getHistories(options: PromptBuildOptions): Promise<{
-        role: "user" | "agent";
-        content: unknown;
-    }[]>;
-    private refineMessages;
+    private mergeMessages;
+    protected deprecatedMemories(message: string | undefined, options: PromptBuildOptions): Promise<ChatModelInputMessage[]>;
     private convertMemoriesToMessages;
     private buildResponseFormat;
     private buildTools;

package/lib/esm/prompt/prompt-builder.js

@@ -1,5 +1,5 @@
-import { AFSHistory } from "@aigne/afs-history";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import { v7 } from "@aigne/uuid";
 import { stringify } from "yaml";
 import { ZodObject } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
@@ -8,9 +8,9 @@ import { DEFAULT_OUTPUT_FILE_KEY, DEFAULT_OUTPUT_KEY } from "../agents/ai-agent.
 import { fileUnionContentsSchema } from "../agents/model.js";
 import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
-import { checkArguments, flat, isNonNullable, isRecord, partition, unique, } from "../utils/type-utils.js";
+import { checkArguments, flat, isRecord, partition, unique } from "../utils/type-utils.js";
+import { AgentSession } from "./agent-session.js";
 import { createPromptBuilderContext } from "./context/index.js";
-import { AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE, getAFSSystemPrompt, } from "./prompts/afs-builtin-prompt.js";
 import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "./prompts/structured-stream-instructions.js";
 import { getAFSSkills } from "./skills/afs/index.js";
@@ -37,10 +37,10 @@ export class PromptBuilder {
                     content = i.content.text;
                 else if (i.content.type === "resource") {
                     const { resource } = i.content;
-                    if (typeof resource.text === "string") {
+                    if ("text" in resource && typeof resource.text === "string") {
                         content = resource.text;
                     }
-                    else if (typeof resource.blob === "string") {
+                    else if ("blob" in resource && typeof resource.blob === "string") {
                         content = [{ type: "url", url: resource.blob }];
                     }
                 }
@@ -70,13 +70,28 @@ export class PromptBuilder {
         });
     }
     async build(options) {
+        let { userId, sessionId } = options.context?.userContext || {};
+        const agentId = options.agent?.name;
+        const afs = options.agent?.afs;
+        sessionId ||= v7();
+        const session = new AgentSession({
+            agentId,
+            userId,
+            sessionId,
+            afs,
+            ...options.agent?.session,
+        });
+        const { systemMessage, userMessage } = await this.buildMessages(options);
+        if (systemMessage)
+            await session.setSystemMessages(systemMessage);
         return {
-            messages: await this.buildMessages(options),
+            userMessage,
             responseFormat: options.agent?.structuredStreamMode
                 ? undefined
                 : this.buildResponseFormat(options),
             outputFileType: options.agent?.outputFileType,
             ...(await this.buildTools(options)),
+            session,
         };
     }
     async buildPrompt(options) {
@@ -99,85 +114,41 @@ export class PromptBuilder {
         const { input } = options;
         const inputKey = options.agent?.inputKey;
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
-        const [messages, otherCustomMessages] = partition((await (typeof this.instructions === "string"
+        const template = typeof this.instructions === "string"
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(this.getTemplateVariables(options), { workingDir: this.workingDir })) ?? [], (i) => i.role === "system");
+            : this.instructions;
+        const [systemMessages, userMessages] = partition((await template?.format(this.getTemplateVariables(options), {
+            workingDir: this.workingDir,
+        })) ?? [], (i) => i.role === "system");
         const inputFileKey = options.agent?.inputFileKey;
         const files = flat(inputFileKey
             ? checkArguments("Check input files", optionalize(fileUnionContentsSchema), input?.[inputFileKey])
             : null);
-        const memories = [];
-        if (options.agent && options.context) {
-            memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
-        }
-        if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
-            memories.push(...options.context.memories);
-        }
-        const afs = options.agent?.afs;
-        if (afs && options.agent?.historyConfig?.disabled !== true) {
-            const historyModule = (await afs.listModules()).find((m) => m.module instanceof AFSHistory);
-            messages.push(await SystemMessageTemplate.from(await getAFSSystemPrompt(afs)).format({}));
-            if (historyModule) {
-                const history = await afs.list(historyModule.path, {
-                    limit: options.agent?.maxRetrieveMemoryCount || 10,
-                    orderBy: [["createdAt", "desc"]],
-                });
-                memories.push(...history.data
-                    .reverse()
-                    .filter((i) => isNonNullable(i.content)));
-                if (message) {
-                    const result = (await afs.search("/", message)).data;
-                    const ms = result
-                        .map((entry) => {
-                        if (entry.metadata?.execute)
-                            return null;
-                        const content = entry.content || entry.summary;
-                        if (!content)
-                            return null;
-                        return {
-                            content,
-                            description: entry.description,
-                        };
-                    })
-                        .filter(isNonNullable);
-                    memories.push(...ms);
-                    const executable = result.filter((i) => !!i.metadata?.execute);
-                    if (executable.length) {
-                        messages.push({
-                            role: "system",
-                            content: await PromptTemplate.from(AFS_EXECUTABLE_TOOLS_PROMPT_TEMPLATE).format({
-                                tools: executable.map((entry) => ({
-                                    path: entry.path,
-                                    name: entry.metadata.execute.name,
-                                    description: entry.metadata.execute.description,
-                                    inputSchema: entry.metadata.execute.inputSchema,
-                                    outputSchema: entry.metadata.execute.outputSchema,
-                                })),
-                            }),
-                        });
-                    }
-                }
-            }
+        if (options.agent?.memories.length || options.context?.memories.length) {
+            const deprecatedMemories = await this.deprecatedMemories(message, options);
+            if (deprecatedMemories.length)
+                systemMessages.push(...deprecatedMemories);
         }
-        if (memories.length)
-            messages.push(...(await this.convertMemoriesToMessages(memories, options)));
         // if the agent is using structured stream mode, add the instructions
         const { structuredStreamMode, outputSchema } = options.agent || {};
         if (structuredStreamMode && outputSchema) {
             const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
                 PromptBuilder.from(STRUCTURED_STREAM_INSTRUCTIONS.instructions);
-            messages.push(...(await instructions.buildMessages({
-                input: {
-                    ...input,
-                    outputJsonSchema: zodToJsonSchema(outputSchema),
-                },
-            })));
+            systemMessages.push({
+                role: "system",
+                content: (await instructions.buildPrompt({
+                    input: {
+                        ...input,
+                        outputJsonSchema: zodToJsonSchema(outputSchema),
+                    },
+                })).prompt,
+            });
         }
         if (message || files.length) {
             const content = [];
             if (message &&
-                // avoid duplicate user messages: developer may have already included the message in the custom user messages
-                !otherCustomMessages.some((i) => i.role === "user" &&
+                // avoid duplicate user messages: developer may have already included the message in the messages
+                !userMessages.some((i) => i.role === "user" &&
                     (typeof i.content === "string"
                         ? i.content.includes(message)
                         : i.content?.some((c) => c.type === "text" && c.text.includes(message))))) {
@@ -186,63 +157,51 @@ export class PromptBuilder {
             if (files.length)
                 content.push(...files);
             if (content.length) {
-                messages.push({ role: "user", content });
+                userMessages.push({ role: "user", content });
             }
         }
-        messages.push(...otherCustomMessages);
-        return this.refineMessages(options, messages);
+        let systemMessage = this.mergeMessages(systemMessages, "system");
+        if (!systemMessage.content?.length)
+            systemMessage = undefined;
+        let userMessage = this.mergeMessages(userMessages, "user");
+        if (!userMessage.content?.length) {
+            userMessage = { role: "user", content: systemMessage?.content };
+            systemMessage = undefined;
+        }
+        if (!userMessage.content?.length)
+            throw new Error("User message cannot be empty.");
+        return {
+            systemMessage,
+            userMessage,
+        };
     }
-    async getHistories(options) {
-        const { agent } = options;
-        const afs = agent?.afs;
-        if (!afs)
-            return [];
-        const historyModule = (await afs.listModules()).find((m) => m.module instanceof AFSHistory);
-        if (!historyModule)
-            return [];
-        const history = (await afs.list(historyModule.path, {
-            limit: agent.historyConfig?.maxItems || 10,
-            orderBy: [["createdAt", "desc"]],
-        })).data;
-        return history
-            .reverse()
-            .map((i) => {
-            if (!i.content)
-                return;
-            const { input, output } = i.content;
-            if (!input || !output)
-                return;
-            return [
-                { role: "user", content: input },
-                { role: "agent", content: output },
-            ];
-        })
-            .filter(isNonNullable)
-            .flat();
+    mergeMessages(messages, role) {
+        const content = [];
+        for (const message of messages) {
+            if (typeof message.content === "string") {
+                content.push({ type: "text", text: message.content });
+            }
+            else if (Array.isArray(message.content)) {
+                content.push(...message.content);
+            }
+            else if (message.content) {
+                throw new Error(`Unsupported message content type: ${typeof message.content}`);
+            }
+        }
+        return { role, content };
     }
-    refineMessages(options, messages) {
-        const { autoReorderSystemMessages, autoMergeSystemMessages } = options.agent ?? {};
-        if (!autoReorderSystemMessages && !autoMergeSystemMessages)
-            return messages;
-        const [systemMessages, otherMessages] = partition(messages, (m) => m.role === "system");
-        if (!autoMergeSystemMessages) {
-            return systemMessages.concat(otherMessages);
+    async deprecatedMemories(message, options) {
+        const messages = [];
+        const memories = [];
+        if (options.agent && options.context) {
+            memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
         }
-        const result = [];
-        if (systemMessages.length) {
-            result.push({
-                role: "system",
-                content: systemMessages
-                    .map((i) => typeof i.content === "string"
-                    ? i.content
-                    : i.content
-                        ?.map((c) => (c.type === "text" ? c.text : null))
-                        .filter(isNonNullable)
-                        .join("\n"))
-                    .join("\n"),
-            });
+        if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
+            memories.push(...options.context.memories);
         }
-        return result.concat(otherMessages);
+        if (memories.length)
+            messages.push(...(await this.convertMemoriesToMessages(memories, options)));
+        return messages;
     }
     async convertMemoriesToMessages(memories, options) {
         const messages = [];

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

@@ -0,0 +1,19 @@
+import { Agent, type AgentOptions, type Message } from "../../../../agents/agent.js";
+import type { PromiseOrValue } from "../../../../utils/type-utils.js";
+import type { Skill } from "./skill-loader.js";
+export interface SkillToolInput extends Message {
+    skill: string;
+    args?: string;
+}
+export interface SkillToolOutput extends Message {
+    result: string;
+}
+export interface SkillToolOptions extends AgentOptions<SkillToolInput, SkillToolOutput> {
+    agentSkills: Skill[];
+}
+export declare class AgentSkill extends Agent<SkillToolInput, SkillToolOutput> {
+    formatOutput(output: SkillToolOutput | Message): PromiseOrValue<string>;
+    constructor(options: SkillToolOptions);
+    private agentSkills;
+    process(input: SkillToolInput): Promise<SkillToolOutput>;
+}

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 {
+    formatOutput(output) {
+        if ("result" in output && typeof output.result === "string") {
+            return output.result;
+        }
+        return super.formatOutput(output);
+    }
+    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,12 @@
+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 discoverSkillsFromAFS(afs: AFS): 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,43 @@
+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 discoverSkillsFromAFS(afs) {
+    const modules = await afs.listModules();
+    const filtered = modules.filter(({ module: m }) => m.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,
+        })
+            .catch(() => ({ data: [] }))).data;
+        for (const entry of data) {
+            const { data: file } = await afs.read(entry.path);
+            if (typeof file?.content !== "string")
+                continue;
+            const dirname = entry.path.split("/").slice(0, -1).join("/");
+            const skill = parseSkill(file.content, dirname);
+            skills.push(skill);
+        }
+    }
+    return skills;
+}
+export async function loadAgentSkillFromAFS({ afs, }) {
+    const skills = await discoverSkillsFromAFS(afs);
+    if (!skills.length)
+        return;
+    return new AgentSkill({
+        agentSkills: skills,
+    });
+}

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

@@ -4,15 +4,27 @@ 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(),