@aigne/core 1.14.0 → 1.16.0

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

@@ -1,9 +1,9 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.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 { Context } from "../aigne/context.js";
 import type { MemoryAgent } from "../memory/memory.js";
-import type { ChatModel, ChatModelInput } from "../models/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
 export declare function createMessage<I extends Message>(message: string | I): I;
@@ -11,7 +11,7 @@ export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuilderBuildOptions {
+export interface PromptBuildOptions {
     memory?: MemoryAgent | MemoryAgent[];
     context: Context;
     agent?: AIAgent;
@@ -32,7 +32,7 @@ export declare class PromptBuilder {
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
-    build(options: PromptBuilderBuildOptions): Promise<ChatModelInput & {
+    build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
     private buildMessages;

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

@@ -1,4 +1,4 @@
-import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../models/chat-model.js";
+import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
@@ -24,7 +24,7 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCalls: ChatModelOutputToolCall[] | undefined;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
@@ -36,7 +36,7 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content: object | string, toolCallId: string, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCallId: string;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCalls?: {
             id: string;

package/lib/cjs/prompt/template.js

@@ -92,7 +92,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content, toolCallId, name) {
         super("tool", typeof content === "string"
             ? content
-            : (0, type_utils_js_1.tryOrThrow)(() => JSON.stringify(content), `Failed to stringify tool content. toolCallId: ${toolCallId}, content: ${(0, node_util_1.inspect)(content)}`), name);
+            : (0, type_utils_js_1.tryOrThrow)(() => JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), `Failed to stringify tool content. toolCallId: ${toolCallId}, content: ${(0, node_util_1.inspect)(content)}`), name);
         this.toolCallId = toolCallId;
     }
     format(variables) {

package/lib/cjs/utils/json-schema.js

@@ -28,7 +28,7 @@ function parseJSON(json) {
         return JSON.parse(json);
     }
     catch (error) {
-        logger_js_1.logger.core("Failed to parse JSON", { json, error });
+        logger_js_1.logger.error("Failed to parse JSON", { json, error });
         throw error;
     }
 }

package/lib/cjs/utils/logger.d.ts

@@ -1,8 +1,33 @@
-import debug from "debug";
-export declare const logger: debug.Debug & {
-    debug: debug.Debug;
-    default: debug.Debug;
-} & {
-    core: debug.Debugger;
-    mcp: debug.Debugger;
-};
+export declare enum LogLevel {
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    DEBUG = "debug"
+}
+export declare class Logger {
+    constructor(options: {
+        level: LogLevel;
+        ns: string;
+    });
+    level: LogLevel;
+    private debugLogger;
+    private infoLogger;
+    private warnLogger;
+    private errorLogger;
+    logMessage: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    logError: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    enabled(level: LogLevel): boolean;
+}
+export declare const logger: Logger;

package/lib/cjs/utils/logger.js

@@ -3,10 +3,68 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = void 0;
+exports.logger = exports.Logger = exports.LogLevel = void 0;
+const node_tty_1 = require("node:tty");
 const debug_1 = __importDefault(require("debug"));
-const base = (0, debug_1.default)("aigne");
-exports.logger = Object.assign(debug_1.default, {
-    core: base.extend("core"),
-    mcp: base.extend("mcp"),
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "error";
+    LogLevel["WARN"] = "warn";
+    LogLevel["INFO"] = "info";
+    LogLevel["DEBUG"] = "debug";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+const levels = Object.values(LogLevel);
+class Logger {
+    constructor(options) {
+        this.level = options.level;
+        this.debugLogger = (0, debug_1.default)(`${options.ns}:debug`);
+        this.infoLogger = (0, debug_1.default)(`${options.ns}:info`);
+        this.warnLogger = (0, debug_1.default)(`${options.ns}:warn`);
+        this.errorLogger = (0, debug_1.default)(`${options.ns}:error`);
+        for (const logger of [this.debugLogger, this.infoLogger, this.warnLogger]) {
+            // @ts-ignore
+            logger.useColors = (0, node_tty_1.isatty)(process.stdout.fd);
+            logger.enabled = true;
+            logger.log = (...args) => this.logMessage(...args);
+        }
+        this.errorLogger.log = (...args) => this.logError(...args);
+        // @ts-ignore
+        this.errorLogger.useColors = (0, node_tty_1.isatty)(process.stderr.fd);
+        this.errorLogger.enabled = true;
+    }
+    level;
+    debugLogger;
+    infoLogger;
+    warnLogger;
+    errorLogger;
+    logMessage = console.log;
+    logError = console.error;
+    debug(message, ...args) {
+        if (this.enabled(LogLevel.DEBUG)) {
+            this.debugLogger(message, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.enabled(LogLevel.INFO)) {
+            this.infoLogger(message, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.enabled(LogLevel.WARN)) {
+            this.warnLogger(message, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (this.enabled(LogLevel.ERROR)) {
+            this.errorLogger(message, ...args);
+        }
+    }
+    enabled(level) {
+        return levels.indexOf(this.level) >= levels.indexOf(level);
+    }
+}
+exports.Logger = Logger;
+exports.logger = new Logger({
+    ns: "aigne:core",
+    level: LogLevel.INFO,
 });

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

@@ -1,3 +1,3 @@
-import type { ChatModelOutputUsage } from "../models/chat-model.js";
+import type { ChatModelOutputUsage } from "../agents/chat-model.js";
 import type { Nullish } from "./type-utils.js";
 export declare function mergeUsage(...usages: Nullish<ChatModelOutputUsage>[]): ChatModelOutputUsage;

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

@@ -6,7 +6,7 @@ export declare function mergeAgentResponseChunk<T extends Message>(output: T, ch
 export declare function agentResponseStreamToObject<T extends Message>(stream: AgentResponseStream<T> | AgentProcessAsyncGenerator<T>): Promise<T>;
 export declare function asyncGeneratorToReadableStream<T extends Message>(generator: AgentProcessAsyncGenerator<T>): AgentResponseStream<T>;
 export declare function onAgentResponseStreamEnd<T extends Message>(stream: AgentResponseStream<T>, callback: (result: T) => PromiseOrValue<Partial<T> | void>, options?: {
-    errorCallback?: (error: Error) => Error;
+    errorCallback?: (error: Error) => PromiseOrValue<Error>;
     processChunk?: (chunk: AgentResponseChunk<T>) => AgentResponseChunk<T>;
 }): ReadableStream<any>;
 export declare function isAsyncGenerator<T extends AsyncGenerator>(value: AsyncGenerator | unknown): value is T;
@@ -18,5 +18,6 @@ export declare function readableStreamToArray<T>(stream: ReadableStream<T>, opti
 export declare function readableStreamToArray<T>(stream: ReadableStream<T>, options?: {
     catchError?: false;
 }): Promise<T[]>;
-export declare function readableStreamToAsyncIterator<T>(stream: ReadableStream<T>): AsyncIterable<T>;
 export declare function stringToAgentResponseStream(str: string, key?: "text" | typeof MESSAGE_KEY | string): AgentResponseStream<Message>;
+export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
+export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;

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

@@ -12,8 +12,9 @@ exports.isAsyncGenerator = isAsyncGenerator;
 exports.arrayToAgentProcessAsyncGenerator = arrayToAgentProcessAsyncGenerator;
 exports.arrayToReadableStream = arrayToReadableStream;
 exports.readableStreamToArray = readableStreamToArray;
-exports.readableStreamToAsyncIterator = readableStreamToAsyncIterator;
 exports.stringToAgentResponseStream = stringToAgentResponseStream;
+exports.toReadableStream = toReadableStream;
+exports.readAllString = readAllString;
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const agent_js_1 = require("../agents/agent.js");
 const type_utils_js_1 = require("./type-utils.js");
@@ -42,7 +43,7 @@ function mergeAgentResponseChunk(output, chunk) {
 async function agentResponseStreamToObject(stream) {
     const json = {};
     if (stream instanceof ReadableStream) {
-        for await (const value of readableStreamToAsyncIterator(stream)) {
+        for await (const value of stream) {
             mergeAgentResponseChunk(json, value);
         }
     }
@@ -92,25 +93,29 @@ function onAgentResponseStreamEnd(stream, callback, options) {
     return new ReadableStream({
         async pull(controller) {
             try {
-                const { value, done } = await reader.read();
-                if (!done) {
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        const result = await callback(json);
+                        if (result && !(0, fast_deep_equal_1.default)(result, json)) {
+                            let chunk = { delta: { json: result } };
+                            if (options?.processChunk)
+                                chunk = options.processChunk(chunk);
+                            controller.enqueue(chunk);
+                        }
+                        controller.close();
+                        return;
+                    }
+                    mergeAgentResponseChunk(json, value);
                     const chunk = options?.processChunk ? options.processChunk(value) : value;
-                    if (!(0, agent_js_1.isEmptyChunk)(chunk))
+                    if (!(0, agent_js_1.isEmptyChunk)(chunk)) {
                         controller.enqueue(chunk);
-                    mergeAgentResponseChunk(json, value);
-                    return;
-                }
-                const result = await callback(json);
-                if (result && !(0, fast_deep_equal_1.default)(result, json)) {
-                    let chunk = { delta: { json: result } };
-                    if (options?.processChunk)
-                        chunk = options.processChunk(chunk);
-                    controller.enqueue(chunk);
+                        break;
+                    }
                 }
-                controller.close();
             }
             catch (error) {
-                controller.error(options?.errorCallback?.(error) ?? error);
+                controller.error((await options?.errorCallback?.(error)) ?? error);
             }
         },
     });
@@ -147,7 +152,7 @@ function arrayToReadableStream(chunks) {
 async function readableStreamToArray(stream, options) {
     const result = [];
     try {
-        for await (const value of readableStreamToAsyncIterator(stream)) {
+        for await (const value of stream) {
             result.push(value);
         }
     }
@@ -158,17 +163,36 @@ async function readableStreamToArray(stream, options) {
     }
     return result;
 }
-async function* readableStreamToAsyncIterator(stream) {
-    const reader = stream.getReader();
-    while (true) {
-        const { value, done } = await reader.read();
-        if (done)
-            break;
-        yield value;
-    }
-}
 function stringToAgentResponseStream(str, key = "text") {
     const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
     const segments = segmenter.segment(str);
     return arrayToReadableStream(Array.from(segments).map((segment) => ({ delta: { text: { [key]: segment.segment } } })));
 }
+function toReadableStream(stream) {
+    return new ReadableStream({
+        start(controller) {
+            const onData = (chunk) => {
+                controller.enqueue(new Uint8Array(chunk));
+            };
+            const onEnd = () => {
+                cleanup();
+                controller.close();
+            };
+            const onError = (err) => {
+                cleanup();
+                controller.error(err);
+            };
+            function cleanup() {
+                stream.off("data", onData);
+                stream.off("end", onEnd);
+                stream.off("error", onError);
+            }
+            stream.on("data", onData);
+            stream.on("end", onEnd);
+            stream.on("error", onError);
+        },
+    });
+}
+async function readAllString(stream) {
+    return (await readableStreamToArray((stream instanceof ReadableStream ? stream : toReadableStream(stream)).pipeThrough(new TextDecoderStream()))).join("");
+}

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

@@ -2,6 +2,11 @@ import { type ZodType } from "zod";
 export type PromiseOrValue<T> = T | Promise<T>;
 export type Nullish<T> = T | null | undefined | void;
 export type OmitPropertiesFromArrayFirstElement<T extends unknown[], K extends string | number | symbol> = T extends [infer U, ...infer Rest] ? [Omit<U, K>, ...Rest] : never;
+export type XOr<T, K extends keyof T, O extends keyof T> = (Omit<T, O> & {
+    [key in O]?: undefined;
+}) | (Omit<T, K> & {
+    [key in K]?: undefined;
+});
 export declare function isNil(value: unknown): value is null | undefined;
 export declare function isRecord<T>(value: unknown): value is Record<string, T>;
 export declare function isEmpty(obj: unknown): boolean;

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

@@ -3,7 +3,8 @@ import { ZodObject, type ZodType } from "zod";
 import type { Context } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
 import type { MemoryAgent } from "../memory/memory.js";
-import { type Nullish, type PromiseOrValue } from "../utils/type-utils.js";
+import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
+import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
 export * from "./types.js";
 /**
@@ -29,7 +30,7 @@ export type PublishTopic<O extends Message> = string | string[] | ((output: O) =
  * @template I The agent input message type
  * @template O The agent output message type
  */
-export interface AgentOptions<I extends Message = Message, O extends Message = Message> {
+export interface AgentOptions<I extends Message = Message, O extends Message = Message> extends Partial<Pick<Agent, "guideRails" | "hooks">> {
     /**
      * Topics the agent should subscribe to
      *
@@ -139,6 +140,35 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Lifecycle hooks for agent processing.
+     *
+     * Hooks enable tracing, logging, monitoring, and custom behavior
+     * without modifying the core agent implementation
+     *
+     * @example
+     * Here's an example of using hooks:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
+     */
+    readonly hooks: AgentHooks;
+    /**
+     * List of GuideRail agents applied to this agent
+     *
+     * GuideRail agents validate, transform, or control the message flow by:
+     * - Enforcing rules and safety policies
+     * - Validating inputs/outputs against specific criteria
+     * - Implementing business logic validations
+     * - Monitoring and auditing agent behavior
+     *
+     * Each GuideRail agent can examine both input and expected output,
+     * and has the ability to abort the process with an explanation
+     *
+     * @example
+     * Here's an example of using GuideRail agents:
+     *
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-guide-rails}
+     */
+    readonly guideRails?: GuideRailAgent[];
     /**
      * Name of the agent, used for identification and logging
      *
@@ -301,6 +331,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @returns Agent response (streaming or regular)
      */
     invoke(input: I | string, context?: Context, options?: AgentInvokeOptions): Promise<AgentResponse<O>>;
+    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, context: Context): Promise<O>;
     /**
      * Process agent output
      *
@@ -319,7 +350,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @param error Caught error
      * @param context Execution context
-     * @throws Always throws the received error
      */
     private processAgentError;
     /**
@@ -342,7 +372,25 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @param _ Input message (unused)
      * @param context Execution context
      */
-    protected preprocess(_: I, context: Context): void;
+    protected preprocess(_: I, context: Context): PromiseOrValue<void>;
+    private checkResponseByGuideRails;
+    private runGuideRails;
+    /**
+     * Handle errors detected by GuideRail agents
+     *
+     * This method is called when a GuideRail agent aborts the process, providing
+     * a way for agents to customize error handling behavior. By default, it simply
+     * returns the original error, but subclasses can override this method to:
+     * - Transform the error into a more specific response
+     * - Apply recovery strategies
+     * - Log or report the error in a custom format
+     * - Return a fallback output instead of an error
+     *
+     * @param error The GuideRail agent output containing abort=true and a reason
+     * @returns Either the original/modified error or a substitute output object
+     *          which will be tagged with $status: "GuideRailError"
+     */
+    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Post-processing operations after handling output
      *
@@ -354,7 +402,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @param output Output message
      * @param context Execution context
      */
-    protected postprocess(input: I, output: O, context: Context): void;
+    protected postprocess(input: I, output: O, context: Context): PromiseOrValue<void>;
     protected publishToTopics(output: Message, context: Context): Promise<void>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
@@ -419,6 +467,81 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      */
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * Lifecycle hooks for agent execution
+ *
+ * Hooks provide a way to intercept and extend agent behavior at key points during
+ * the agent's lifecycle, enabling custom functionality like logging, monitoring,
+ * tracing, error handling, and more.
+ */
+export interface AgentHooks<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Called when agent processing begins
+     *
+     * This hook runs before the agent processes input, allowing for
+     * setup operations, logging, or input transformations.
+     *
+     * @param event Object containing the input message
+     */
+    onStart?: (event: {
+        input: I;
+    }) => PromiseOrValue<void>;
+    /**
+     * Called when agent processing completes or fails
+     *
+     * This hook runs after processing finishes, receiving either the output
+     * or an error if processing failed. Useful for cleanup operations,
+     * logging results, or error handling.
+     *
+     * @param event Object containing the input message and either output or error
+     */
+    onEnd?: (event: XOr<{
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">) => PromiseOrValue<void>;
+    /**
+     * Called before a skill (sub-agent) is invoked
+     *
+     * This hook runs when the agent delegates work to a skill,
+     * allowing for tracking skill usage or transforming input to the skill.
+     *
+     * @param event Object containing the skill being used and input message
+     */
+    onSkillStart?: (event: {
+        skill: Agent;
+        input: I;
+    }) => PromiseOrValue<void>;
+    /**
+     * Called after a skill (sub-agent) completes or fails
+     *
+     * This hook runs when a skill finishes execution, receiving either the output
+     * or an error if the skill failed. Useful for monitoring skill performance
+     * or handling skill-specific errors.
+     *
+     * @param event Object containing the skill used, input message, and either output or error
+     */
+    onSkillEnd?: (event: XOr<{
+        skill: Agent;
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">) => PromiseOrValue<void>;
+    /**
+     * Called when an agent hands off processing to another agent
+     *
+     * This hook runs when a source agent transfers control to a target agent,
+     * allowing for tracking of handoffs between agents and monitoring the flow
+     * of processing in multi-agent systems.
+     *
+     * @param event Object containing the source agent, target agent, and input message
+     */
+    onHandoff?: (event: {
+        source: Agent;
+        target: Agent;
+        input: I;
+    }) => PromiseOrValue<void>;
+}
 /**
  * Response type for an agent, can be:
  * - Direct response object
@@ -427,7 +550,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
  *
  * @template T Response data type
  */
-export type AgentResponse<T> = T | TransferAgentOutput | AgentResponseStream<T>;
+export type AgentResponse<T> = T | AgentResponseStream<T> | TransferAgentOutput | GuideRailAgentOutput;
 /**
  * Streaming response type for an agent
  *

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

@@ -1,10 +1,10 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import type { Context } from "../aigne/context.js";
 import { type DefaultMemoryOptions } from "../memory/default-memory.js";
-import { ChatModel } from "../models/chat-model.js";
-import type { ChatModelInput } from "../models/chat-model.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { ChatModel, type ChatModelInput } from "./chat-model.js";
+import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
 /**
  * Configuration options for an AI Agent
  *
@@ -216,6 +216,7 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      * @protected
      */
     process(input: I, context: Context): AgentProcessAsyncGenerator<O>;
+    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests
      *