@aigne/core 1.57.2 → 1.57.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.57.3](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.57.2...core-v1.57.3) (2025-08-30)
+
+
+### Bug Fixes
+
+* **core:** improve nested prompt file resolution ([#437](https://github.com/AIGNE-io/aigne-framework/issues/437)) ([38b5b13](https://github.com/AIGNE-io/aigne-framework/commit/38b5b1397b7897cddef39d60c8cae2152e37dc5b))
+
 ## [1.57.2](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.57.1...core-v1.57.2) (2025-08-29)
 
 

package/lib/cjs/loader/agent-yaml.d.ts

@@ -32,16 +32,20 @@ export interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
+export type Instructions = {
+    content: string;
+    path: string;
+};
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
-    instructions?: string;
+    instructions?: Instructions;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
-    instructions: string;
+    instructions: Instructions;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

package/lib/cjs/loader/agent-yaml.js

@@ -58,8 +58,8 @@ async function parseAgentFile(path, data) {
             }),
         ])
             .transform((v) => typeof v === "string"
-            ? v
-            : v && index_js_1.nodejs.fs.readFile(index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), v.url), "utf8"));
+            ? { content: v, path }
+            : Promise.resolve(index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), v.url)).then((path) => index_js_1.nodejs.fs.readFile(path, "utf8").then((content) => ({ content, path }))));
         return (0, schema_js_1.camelizeSchema)(zod_1.z.discriminatedUnion("type", [
             zod_1.z
                 .object({

package/lib/cjs/loader/index.d.ts

@@ -14,9 +14,7 @@ export interface LoadOptions {
     key?: string | number;
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
-export declare function loadAgent(path: string, options?: LoadOptions & {
-    rootDir?: string;
-}, agentOptions?: AgentOptions): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
     description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;

package/lib/cjs/loader/index.js

@@ -22,10 +22,7 @@ async function load(path, options = {}) {
     options.key ??= Date.now();
     const { aigne, rootDir } = await loadAIGNEFile(path);
     const allAgentPaths = new Set((0, type_utils_js_1.flat)(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.agents, aigne.cli?.chat).map((i) => index_js_1.nodejs.path.join(rootDir, i)));
-    const allAgents = Object.fromEntries(await Promise.all(Array.from(allAgentPaths).map(async (path) => [
-        path,
-        await loadAgent(path, { ...options, rootDir }),
-    ])));
+    const allAgents = Object.fromEntries(await Promise.all(Array.from(allAgentPaths).map(async (path) => [path, await loadAgent(path, options)])));
     const pickAgents = (paths) => paths.map((filename) => allAgents[index_js_1.nodejs.path.join(rootDir, filename)]).filter(type_utils_js_1.isNonNullable);
     return {
         ...aigne,
@@ -88,7 +85,6 @@ async function parseHooks(path, hooks, options) {
     })));
 }
 async function parseAgent(path, agent, options, agentOptions) {
-    const workingDir = options?.rootDir ?? index_js_1.nodejs.path.dirname(path);
     const skills = "skills" in agent
         ? agent.skills &&
             (await Promise.all(agent.skills.map((skill) => loadNestAgent(path, skill, options))))
@@ -106,17 +102,25 @@ async function parseAgent(path, agent, options, agentOptions) {
             ...[agentOptions?.hooks].flat().filter(type_utils_js_1.isNonNullable),
         ],
     };
+    let instructions;
+    if ("instructions" in agent && agent.instructions) {
+        instructions = prompt_builder_js_1.PromptBuilder.from(agent.instructions.content, {
+            workingDir: index_js_1.nodejs.path.dirname(agent.instructions.path),
+        });
+    }
     switch (agent.type) {
         case "ai": {
             return ai_agent_js_1.AIAgent.from({
                 ...baseOptions,
-                instructions: agent.instructions && prompt_builder_js_1.PromptBuilder.from(agent.instructions, { workingDir }),
+                instructions,
             });
         }
         case "image": {
+            if (!instructions)
+                throw new Error(`Missing required instructions for image agent at path: ${path}`);
             return image_agent_js_1.ImageAgent.from({
                 ...baseOptions,
-                instructions: prompt_builder_js_1.PromptBuilder.from(agent.instructions, { workingDir }),
+                instructions,
             });
         }
         case "mcp": {

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

@@ -17,7 +17,6 @@ export declare class CustomLoader extends nunjucks.Loader {
         workingDir: string;
     });
     async: boolean;
-    private findFile;
     getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {

package/lib/cjs/prompt/template.js

@@ -38,7 +38,6 @@ class PromptTemplate {
     }
 }
 exports.PromptTemplate = PromptTemplate;
-const IGNORED_PROMPT_DIRS = ["node_modules", ".git"];
 class CustomLoader extends nunjucks_1.default.Loader {
     options;
     constructor(options) {
@@ -46,39 +45,20 @@ class CustomLoader extends nunjucks_1.default.Loader {
         this.options = options;
     }
     async = true;
-    async findFile(dir, name) {
-        name = name.replace(/^[./]*/, "");
-        const files = await index_js_1.nodejs.fs.readdir(dir, { withFileTypes: true });
-        const file = files.find((f) => index_js_1.nodejs.path.join(f.parentPath, f.name).endsWith(name));
-        if (file)
-            return index_js_1.nodejs.path.join(file.parentPath, file.name);
-        for (const entry of files) {
-            if (entry.isDirectory()) {
-                if (IGNORED_PROMPT_DIRS.includes(entry.name))
-                    continue;
-                const result = await this.findFile(index_js_1.nodejs.path.join(entry.parentPath, entry.name), name);
-                if (result)
-                    return result;
-            }
-        }
-    }
     getSource(name, callback) {
         let result = null;
-        this.findFile(this.options.workingDir, name).then((path) => {
-            if (!path) {
-                callback(new Error(`Template not found: ${name}`), null);
-                return;
-            }
-            return index_js_1.nodejs.fs.readFile(path, "utf-8").then((content) => {
-                result = {
-                    src: content,
-                    path: name,
-                    noCache: true,
-                };
-                callback(null, result);
-            }, (error) => {
-                callback(error, null);
-            });
+        const path = index_js_1.nodejs.path.isAbsolute(name)
+            ? name
+            : index_js_1.nodejs.path.join(this.options.workingDir, name);
+        index_js_1.nodejs.fs.readFile(path, "utf-8").then((content) => {
+            result = {
+                src: content,
+                path,
+                noCache: true,
+            };
+            callback(null, result);
+        }, (error) => {
+            callback(error, null);
         });
         // nunjucks expects return LoaderSource synchronously, but we handle it asynchronously.
         return result;

package/lib/dts/loader/agent-yaml.d.ts

@@ -32,16 +32,20 @@ export interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
+export type Instructions = {
+    content: string;
+    path: string;
+};
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
-    instructions?: string;
+    instructions?: Instructions;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
-    instructions: string;
+    instructions: Instructions;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

package/lib/dts/loader/index.d.ts

@@ -14,9 +14,7 @@ export interface LoadOptions {
     key?: string | number;
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
-export declare function loadAgent(path: string, options?: LoadOptions & {
-    rootDir?: string;
-}, agentOptions?: AgentOptions): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
     description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;

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

@@ -17,7 +17,6 @@ export declare class CustomLoader extends nunjucks.Loader {
         workingDir: string;
     });
     async: boolean;
-    private findFile;
     getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {

package/lib/esm/loader/agent-yaml.d.ts

@@ -32,16 +32,20 @@ export interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
+export type Instructions = {
+    content: string;
+    path: string;
+};
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
-    instructions?: string;
+    instructions?: Instructions;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
-    instructions: string;
+    instructions: Instructions;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

package/lib/esm/loader/agent-yaml.js

@@ -54,8 +54,8 @@ export async function parseAgentFile(path, data) {
             }),
         ])
             .transform((v) => typeof v === "string"
-            ? v
-            : v && nodejs.fs.readFile(nodejs.path.join(nodejs.path.dirname(path), v.url), "utf8"));
+            ? { content: v, path }
+            : Promise.resolve(nodejs.path.join(nodejs.path.dirname(path), v.url)).then((path) => nodejs.fs.readFile(path, "utf8").then((content) => ({ content, path }))));
         return camelizeSchema(z.discriminatedUnion("type", [
             z
                 .object({

package/lib/esm/loader/index.d.ts

@@ -14,9 +14,7 @@ export interface LoadOptions {
     key?: string | number;
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
-export declare function loadAgent(path: string, options?: LoadOptions & {
-    rootDir?: string;
-}, agentOptions?: AgentOptions): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
     description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;

package/lib/esm/loader/index.js

@@ -17,10 +17,7 @@ export async function load(path, options = {}) {
     options.key ??= Date.now();
     const { aigne, rootDir } = await loadAIGNEFile(path);
     const allAgentPaths = new Set(flat(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.agents, aigne.cli?.chat).map((i) => nodejs.path.join(rootDir, i)));
-    const allAgents = Object.fromEntries(await Promise.all(Array.from(allAgentPaths).map(async (path) => [
-        path,
-        await loadAgent(path, { ...options, rootDir }),
-    ])));
+    const allAgents = Object.fromEntries(await Promise.all(Array.from(allAgentPaths).map(async (path) => [path, await loadAgent(path, options)])));
     const pickAgents = (paths) => paths.map((filename) => allAgents[nodejs.path.join(rootDir, filename)]).filter(isNonNullable);
     return {
         ...aigne,
@@ -83,7 +80,6 @@ async function parseHooks(path, hooks, options) {
     })));
 }
 async function parseAgent(path, agent, options, agentOptions) {
-    const workingDir = options?.rootDir ?? nodejs.path.dirname(path);
     const skills = "skills" in agent
         ? agent.skills &&
             (await Promise.all(agent.skills.map((skill) => loadNestAgent(path, skill, options))))
@@ -101,17 +97,25 @@ async function parseAgent(path, agent, options, agentOptions) {
             ...[agentOptions?.hooks].flat().filter(isNonNullable),
         ],
     };
+    let instructions;
+    if ("instructions" in agent && agent.instructions) {
+        instructions = PromptBuilder.from(agent.instructions.content, {
+            workingDir: nodejs.path.dirname(agent.instructions.path),
+        });
+    }
     switch (agent.type) {
         case "ai": {
             return AIAgent.from({
                 ...baseOptions,
-                instructions: agent.instructions && PromptBuilder.from(agent.instructions, { workingDir }),
+                instructions,
             });
         }
         case "image": {
+            if (!instructions)
+                throw new Error(`Missing required instructions for image agent at path: ${path}`);
             return ImageAgent.from({
                 ...baseOptions,
-                instructions: PromptBuilder.from(agent.instructions, { workingDir }),
+                instructions,
             });
         }
         case "mcp": {

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

@@ -17,7 +17,6 @@ export declare class CustomLoader extends nunjucks.Loader {
         workingDir: string;
     });
     async: boolean;
-    private findFile;
     getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {

package/lib/esm/prompt/template.js

@@ -30,7 +30,6 @@ export class PromptTemplate {
         }));
     }
 }
-const IGNORED_PROMPT_DIRS = ["node_modules", ".git"];
 export class CustomLoader extends nunjucks.Loader {
     options;
     constructor(options) {
@@ -38,39 +37,20 @@ export class CustomLoader extends nunjucks.Loader {
         this.options = options;
     }
     async = true;
-    async findFile(dir, name) {
-        name = name.replace(/^[./]*/, "");
-        const files = await nodejs.fs.readdir(dir, { withFileTypes: true });
-        const file = files.find((f) => nodejs.path.join(f.parentPath, f.name).endsWith(name));
-        if (file)
-            return nodejs.path.join(file.parentPath, file.name);
-        for (const entry of files) {
-            if (entry.isDirectory()) {
-                if (IGNORED_PROMPT_DIRS.includes(entry.name))
-                    continue;
-                const result = await this.findFile(nodejs.path.join(entry.parentPath, entry.name), name);
-                if (result)
-                    return result;
-            }
-        }
-    }
     getSource(name, callback) {
         let result = null;
-        this.findFile(this.options.workingDir, name).then((path) => {
-            if (!path) {
-                callback(new Error(`Template not found: ${name}`), null);
-                return;
-            }
-            return nodejs.fs.readFile(path, "utf-8").then((content) => {
-                result = {
-                    src: content,
-                    path: name,
-                    noCache: true,
-                };
-                callback(null, result);
-            }, (error) => {
-                callback(error, null);
-            });
+        const path = nodejs.path.isAbsolute(name)
+            ? name
+            : nodejs.path.join(this.options.workingDir, name);
+        nodejs.fs.readFile(path, "utf-8").then((content) => {
+            result = {
+                src: content,
+                path,
+                noCache: true,
+            };
+            callback(null, result);
+        }, (error) => {
+            callback(error, null);
         });
         // nunjucks expects return LoaderSource synchronously, but we handle it asynchronously.
         return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.57.2",
+  "version": "1.57.3",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"