@aigne/core 1.49.1 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.50.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.49.1...core-v1.50.0) (2025-08-14)
+
+
+### Features
+
+* **core:** add priority support for agent hooks ([#358](https://github.com/AIGNE-io/aigne-framework/issues/358)) ([9196141](https://github.com/AIGNE-io/aigne-framework/commit/91961413aea171048a6afae87ffc8dc53e20fca8))
+
+
+### Bug Fixes
+
+* **cli:** log only once in loadAIGNE ([#357](https://github.com/AIGNE-io/aigne-framework/issues/357)) ([6e6d968](https://github.com/AIGNE-io/aigne-framework/commit/6e6d96814fbc87f210522ae16daf94c1f84f311a))
+* **cli:** prevent multiple simultaneous buy credits prompts ([#363](https://github.com/AIGNE-io/aigne-framework/issues/363)) ([b8fb459](https://github.com/AIGNE-io/aigne-framework/commit/b8fb459261fe327bcc9bfb4d163e66863cb797ec))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.6.2
+
 ## [1.49.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.49.0...core-v1.49.1) (2025-08-12)
 
 

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

@@ -545,6 +545,7 @@ export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : n
  * tracing, error handling, and more.
  */
 export interface AgentHooks<I extends Message = Message, O extends Message = Message> {
+    priority?: "low" | "medium" | "high";
     /**
      * Called when agent processing begins
      *

package/lib/cjs/agents/agent.js

@@ -50,6 +50,7 @@ const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_1 = require("zod");
+const agent_utils_js_1 = require("../utils/agent-utils.js");
 const logger_js_1 = require("../utils/logger.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
@@ -388,15 +389,15 @@ class Agent {
                 yield { delta: { json: resetOutput } };
                 output = {};
             }
-            let response = await this.process(input, options);
-            if (response instanceof Agent)
-                response = (0, types_js_1.transferToAgentOutput)(response);
-            const stream = response instanceof ReadableStream
-                ? response
-                : (0, stream_utils_js_1.isAsyncGenerator)(response)
-                    ? (0, stream_utils_js_1.asyncGeneratorToReadableStream)(response)
-                    : (0, stream_utils_js_1.objectToAgentResponseStream)(response);
             try {
+                let response = await this.process(input, options);
+                if (response instanceof Agent)
+                    response = (0, types_js_1.transferToAgentOutput)(response);
+                const stream = response instanceof ReadableStream
+                    ? response
+                    : (0, stream_utils_js_1.isAsyncGenerator)(response)
+                        ? (0, stream_utils_js_1.asyncGeneratorToReadableStream)(response)
+                        : (0, stream_utils_js_1.objectToAgentResponseStream)(response);
                 for await (const chunk of stream) {
                     (0, stream_utils_js_1.mergeAgentResponseChunk)(output, chunk);
                     yield chunk;
@@ -418,16 +419,20 @@ class Agent {
     async callHooks(hook, input, options) {
         const { context } = options;
         const result = {};
-        for (const hooks of (0, type_utils_js_1.flat)(options.hooks, options.context.hooks, this.hooks)) {
-            const h = hooks[hook];
-            if (!h)
-                continue;
+        const hs = (0, type_utils_js_1.flat)(hook);
+        const hooks = (0, agent_utils_js_1.sortHooks)((0, type_utils_js_1.flat)(options.hooks, options.context.hooks, this.hooks))
+            .flatMap((hooks) => hs.map((h) => hooks[h]))
+            .filter(type_utils_js_1.isNonNullable);
+        for (const h of hooks) {
             if (typeof h === "function") {
                 Object.assign(result, await h({ ...input, context, agent: this }));
             }
             else {
                 Object.assign(result, await context.invoke(h, { ...input, agent: this }));
             }
+            // If the hook returns a retry signal, we stop processing further hooks
+            if ("retry" in result && result.retry)
+                return result;
         }
         return result;
     }
@@ -480,10 +485,7 @@ class Agent {
         let finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
         await this.postprocess(input, finalOutput, options);
         logger_js_1.logger.debug("Invoke agent %s succeed with output: %O", this.name, finalOutput);
-        let o = await this.callHooks("onSuccess", { input, output: finalOutput }, options);
-        if (o?.output)
-            finalOutput = o.output;
-        o = await this.callHooks("onEnd", { input, output: finalOutput }, options);
+        const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
         if (!this.disableEvents)
@@ -505,8 +507,7 @@ class Agent {
         logger_js_1.logger.error("Invoke agent %s failed with error: %O", this.name, error);
         if (!this.disableEvents)
             options.context.emit("agentFailed", { agent: this, error });
-        const res = (await this.callHooks("onError", { input, error }, options)) ?? {};
-        Object.assign(res, await this.callHooks("onEnd", { input, error }, options));
+        const res = (await this.callHooks(["onError", "onEnd"], { input, error }, options)) ?? {};
         return { ...res };
     }
     /**

package/lib/cjs/agents/chat-model.d.ts

@@ -26,6 +26,11 @@ import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message }
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     tag: string;
     constructor();
+    abstract getCredential(): {
+        url?: string;
+        apiKey?: string;
+        model?: string;
+    };
     /**
      * Indicates whether the model supports parallel tool calls
      *

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

@@ -1,8 +1,9 @@
 import { type ZodType } from "zod";
-import type { FunctionAgentFn } from "../agents/agent.js";
+import type { AgentHooks, FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 export interface HooksSchema {
+    priority?: AgentHooks["priority"];
     onStart?: NestAgentSchema;
     onSuccess?: NestAgentSchema;
     onError?: NestAgentSchema;

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

@@ -22,6 +22,7 @@ async function parseAgentFile(path, data) {
             })),
         ]));
         const hooksSchema = (0, schema_js_1.camelizeSchema)(zod_1.z.object({
+            priority: (0, schema_js_1.optionalize)(zod_1.z.union([zod_1.z.literal("low"), zod_1.z.literal("medium"), zod_1.z.literal("high")])),
             onStart: (0, schema_js_1.optionalize)(nestAgentSchema),
             onSuccess: (0, schema_js_1.optionalize)(nestAgentSchema),
             onError: (0, schema_js_1.optionalize)(nestAgentSchema),

package/lib/cjs/loader/index.js

@@ -64,6 +64,7 @@ async function parseHooks(path, hooks, options) {
     if (!hooks.length)
         return undefined;
     return await Promise.all(hooks.map(async (hook) => ({
+        priority: hook.priority,
         onStart: hook.onStart ? await loadNestAgent(path, hook.onStart, options) : undefined,
         onSuccess: hook.onSuccess ? await loadNestAgent(path, hook.onSuccess, options) : undefined,
         onError: hook.onError ? await loadNestAgent(path, hook.onError, options) : undefined,

package/lib/cjs/utils/agent-utils.d.ts

@@ -0,0 +1,2 @@
+import type { AgentHooks } from "../agents/agent.ts";
+export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];

package/lib/cjs/utils/agent-utils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortHooks = sortHooks;
+const priorities = ["high", "medium", "low"];
+function sortHooks(hooks) {
+    return hooks
+        .slice(0)
+        .sort(({ priority: a = "low" }, { priority: b = "low" }) => a === b ? 0 : priorities.indexOf(a) - priorities.indexOf(b));
+}

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

@@ -545,6 +545,7 @@ export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : n
  * tracing, error handling, and more.
  */
 export interface AgentHooks<I extends Message = Message, O extends Message = Message> {
+    priority?: "low" | "medium" | "high";
     /**
      * Called when agent processing begins
      *

package/lib/dts/agents/chat-model.d.ts

@@ -26,6 +26,11 @@ import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message }
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     tag: string;
     constructor();
+    abstract getCredential(): {
+        url?: string;
+        apiKey?: string;
+        model?: string;
+    };
     /**
      * Indicates whether the model supports parallel tool calls
      *

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

@@ -1,8 +1,9 @@
 import { type ZodType } from "zod";
-import type { FunctionAgentFn } from "../agents/agent.js";
+import type { AgentHooks, FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 export interface HooksSchema {
+    priority?: AgentHooks["priority"];
     onStart?: NestAgentSchema;
     onSuccess?: NestAgentSchema;
     onError?: NestAgentSchema;

package/lib/dts/utils/agent-utils.d.ts

@@ -0,0 +1,2 @@
+import type { AgentHooks } from "../agents/agent.ts";
+export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];

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

@@ -545,6 +545,7 @@ export type AgentOutput<T extends Agent> = T extends Agent<any, infer O> ? O : n
  * tracing, error handling, and more.
  */
 export interface AgentHooks<I extends Message = Message, O extends Message = Message> {
+    priority?: "low" | "medium" | "high";
     /**
      * Called when agent processing begins
      *

package/lib/esm/agents/agent.js

@@ -2,9 +2,10 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import equal from "fast-deep-equal";
 import nunjucks from "nunjucks";
 import { ZodObject, z } from "zod";
+import { sortHooks } from "../utils/agent-utils.js";
 import { logger } from "../utils/logger.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, isAsyncGenerator, mergeAgentResponseChunk, objectToAgentResponseStream, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
-import { checkArguments, createAccessorArray, flat, isEmpty, isNil, isRecord, } from "../utils/type-utils.js";
+import { checkArguments, createAccessorArray, flat, isEmpty, isNil, isNonNullable, isRecord, } from "../utils/type-utils.js";
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
 export * from "./types.js";
 export const DEFAULT_INPUT_ACTION_GET = "$get";
@@ -340,15 +341,15 @@ export class Agent {
                 yield { delta: { json: resetOutput } };
                 output = {};
             }
-            let response = await this.process(input, options);
-            if (response instanceof Agent)
-                response = transferToAgentOutput(response);
-            const stream = response instanceof ReadableStream
-                ? response
-                : isAsyncGenerator(response)
-                    ? asyncGeneratorToReadableStream(response)
-                    : objectToAgentResponseStream(response);
             try {
+                let response = await this.process(input, options);
+                if (response instanceof Agent)
+                    response = transferToAgentOutput(response);
+                const stream = response instanceof ReadableStream
+                    ? response
+                    : isAsyncGenerator(response)
+                        ? asyncGeneratorToReadableStream(response)
+                        : objectToAgentResponseStream(response);
                 for await (const chunk of stream) {
                     mergeAgentResponseChunk(output, chunk);
                     yield chunk;
@@ -370,16 +371,20 @@ export class Agent {
     async callHooks(hook, input, options) {
         const { context } = options;
         const result = {};
-        for (const hooks of flat(options.hooks, options.context.hooks, this.hooks)) {
-            const h = hooks[hook];
-            if (!h)
-                continue;
+        const hs = flat(hook);
+        const hooks = sortHooks(flat(options.hooks, options.context.hooks, this.hooks))
+            .flatMap((hooks) => hs.map((h) => hooks[h]))
+            .filter(isNonNullable);
+        for (const h of hooks) {
             if (typeof h === "function") {
                 Object.assign(result, await h({ ...input, context, agent: this }));
             }
             else {
                 Object.assign(result, await context.invoke(h, { ...input, agent: this }));
             }
+            // If the hook returns a retry signal, we stop processing further hooks
+            if ("retry" in result && result.retry)
+                return result;
         }
         return result;
     }
@@ -432,10 +437,7 @@ export class Agent {
         let finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
         await this.postprocess(input, finalOutput, options);
         logger.debug("Invoke agent %s succeed with output: %O", this.name, finalOutput);
-        let o = await this.callHooks("onSuccess", { input, output: finalOutput }, options);
-        if (o?.output)
-            finalOutput = o.output;
-        o = await this.callHooks("onEnd", { input, output: finalOutput }, options);
+        const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
         if (!this.disableEvents)
@@ -457,8 +459,7 @@ export class Agent {
         logger.error("Invoke agent %s failed with error: %O", this.name, error);
         if (!this.disableEvents)
             options.context.emit("agentFailed", { agent: this, error });
-        const res = (await this.callHooks("onError", { input, error }, options)) ?? {};
-        Object.assign(res, await this.callHooks("onEnd", { input, error }, options));
+        const res = (await this.callHooks(["onError", "onEnd"], { input, error }, options)) ?? {};
         return { ...res };
     }
     /**

package/lib/esm/agents/chat-model.d.ts

@@ -26,6 +26,11 @@ import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message }
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     tag: string;
     constructor();
+    abstract getCredential(): {
+        url?: string;
+        apiKey?: string;
+        model?: string;
+    };
     /**
      * Indicates whether the model supports parallel tool calls
      *

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

@@ -1,8 +1,9 @@
 import { type ZodType } from "zod";
-import type { FunctionAgentFn } from "../agents/agent.js";
+import type { AgentHooks, FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 export interface HooksSchema {
+    priority?: AgentHooks["priority"];
     onStart?: NestAgentSchema;
     onSuccess?: NestAgentSchema;
     onError?: NestAgentSchema;

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

@@ -18,6 +18,7 @@ export async function parseAgentFile(path, data) {
             })),
         ]));
         const hooksSchema = camelizeSchema(z.object({
+            priority: optionalize(z.union([z.literal("low"), z.literal("medium"), z.literal("high")])),
             onStart: optionalize(nestAgentSchema),
             onSuccess: optionalize(nestAgentSchema),
             onError: optionalize(nestAgentSchema),

package/lib/esm/loader/index.js

@@ -59,6 +59,7 @@ async function parseHooks(path, hooks, options) {
     if (!hooks.length)
         return undefined;
     return await Promise.all(hooks.map(async (hook) => ({
+        priority: hook.priority,
         onStart: hook.onStart ? await loadNestAgent(path, hook.onStart, options) : undefined,
         onSuccess: hook.onSuccess ? await loadNestAgent(path, hook.onSuccess, options) : undefined,
         onError: hook.onError ? await loadNestAgent(path, hook.onError, options) : undefined,

package/lib/esm/utils/agent-utils.d.ts

@@ -0,0 +1,2 @@
+import type { AgentHooks } from "../agents/agent.ts";
+export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];

package/lib/esm/utils/agent-utils.js

@@ -0,0 +1,6 @@
+const priorities = ["high", "medium", "low"];
+export function sortHooks(hooks) {
+    return hooks
+        .slice(0)
+        .sort(({ priority: a = "low" }, { priority: b = "low" }) => a === b ? 0 : priorities.indexOf(a) - priorities.indexOf(b));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.49.1",
+  "version": "1.50.0",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -90,7 +90,7 @@
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
     "@aigne/observability-api": "^0.9.0",
-    "@aigne/platform-helpers": "^0.6.1"
+    "@aigne/platform-helpers": "^0.6.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.18",