@aigne/core 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,26 +1,23 @@
-## [1.3.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.2.0...core-v1.3.0) (2025-03-24)
+## [1.17.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.16.0...core-v1.17.0) (2025-05-25)
 
 
 ### Features
 
-* add Agent FunctionAgent AIAgent MCPAgent and ExecutionEngine ([4d2a5a1](https://github.com/AIGNE-io/aigne-framework/commit/4d2a5a1b3366b8f935f50a0937c2da6e49073348))
-* add OrchestratorAgent in agent library ([25a5e9e](https://github.com/AIGNE-io/aigne-framework/commit/25a5e9e6c60d747c8bf484ac884b31dc02c14757))
-* add sequential and parallel helper function ([a295697](https://github.com/AIGNE-io/aigne-framework/commit/a295697b5694754e02954fc5c7f382a3b219a3ab))
-* add support for MCP resources ([1ded2fb](https://github.com/AIGNE-io/aigne-framework/commit/1ded2fbf222fa8984e75df0852ff384524f73b04))
-* **core:** add ChatModelClaude to use models of anthropic ([#30](https://github.com/AIGNE-io/aigne-framework/issues/30)) ([0a62a64](https://github.com/AIGNE-io/aigne-framework/commit/0a62a6499e3da723a4646e67952051708ce7de6a))
-* **core:** add support for subscribing topics for agent memory ([#28](https://github.com/AIGNE-io/aigne-framework/issues/28)) ([eeecc67](https://github.com/AIGNE-io/aigne-framework/commit/eeecc67049a60ebcc4cdba0fbcd987b3d81f4af6))
-* **prompt-builder:** support chat history in PromptBuilder ([6ca05f2](https://github.com/AIGNE-io/aigne-framework/commit/6ca05f28eddb683a4f1e228865f8bbf8a8e190f1))
-* support run puppeteer example chat loop in terminal ([85ce7f8](https://github.com/AIGNE-io/aigne-framework/commit/85ce7f8de8b443c86e50815dd7bcab99f869c4ce))
-* use PromptBuilder instead of string instructions ([e4cb2cb](https://github.com/AIGNE-io/aigne-framework/commit/e4cb2cb6baf4f9bcef390567a4a174e9246c29a3))
+* add user context support ([#131](https://github.com/AIGNE-io/aigne-framework/issues/131)) ([4dd9d20](https://github.com/AIGNE-io/aigne-framework/commit/4dd9d20953f6ac33933723db56efd9b44bafeb02))
 
+## [1.18.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.17.0...core-v1.18.0) (2025-05-29)
 
-### Bug Fixes
 
-* **AIAgent:** should pass both arguments (model generated) and input (user input) to tool ([c49d64e](https://github.com/AIGNE-io/aigne-framework/commit/c49d64ee35f7efd83b0f82f43205bb1c40f999e8))
-* **core:** enforce stricter input/output type checks ([#26](https://github.com/AIGNE-io/aigne-framework/issues/26)) ([ef8cf53](https://github.com/AIGNE-io/aigne-framework/commit/ef8cf53586aff08a809909c56ab2a20f215fa129))
-* **MCP:** catch list resource error treat as empty list ([1885fab](https://github.com/AIGNE-io/aigne-framework/commit/1885fab3585e0dd1467b127e5b47cd0b98282bab))
-* rename @aigne/core-next to @aigne/core ([3a81009](https://github.com/AIGNE-io/aigne-framework/commit/3a8100962c81813217b687ae28e8de604419c622))
-* use text resource from MCP correctly ([8b9eba8](https://github.com/AIGNE-io/aigne-framework/commit/8b9eba83352ec096a2a5d4f410d4c4bde7420bce))
+### Features
+
+* add memory agents support for client agent ([#139](https://github.com/AIGNE-io/aigne-framework/issues/139)) ([57044fa](https://github.com/AIGNE-io/aigne-framework/commit/57044fa87b8abcba395cd05f941d6d312ab65764))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.1.0
 
 ## [1.16.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.15.0...core-v1.16.0) (2025-05-23)
 
@@ -201,6 +198,30 @@
 
 * **core:** use system message as user message for claude model if needed ([#32](https://github.com/AIGNE-io/aigne-framework/issues/32)) ([316a6d5](https://github.com/AIGNE-io/aigne-framework/commit/316a6d51f885cceee4020c24695f6588f6b7425f))
 
+## [1.3.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.2.0...core-v1.3.0) (2025-03-24)
+
+
+### Features
+
+* add Agent FunctionAgent AIAgent MCPAgent and ExecutionEngine ([4d2a5a1](https://github.com/AIGNE-io/aigne-framework/commit/4d2a5a1b3366b8f935f50a0937c2da6e49073348))
+* add OrchestratorAgent in agent library ([25a5e9e](https://github.com/AIGNE-io/aigne-framework/commit/25a5e9e6c60d747c8bf484ac884b31dc02c14757))
+* add sequential and parallel helper function ([a295697](https://github.com/AIGNE-io/aigne-framework/commit/a295697b5694754e02954fc5c7f382a3b219a3ab))
+* add support for MCP resources ([1ded2fb](https://github.com/AIGNE-io/aigne-framework/commit/1ded2fbf222fa8984e75df0852ff384524f73b04))
+* **core:** add ChatModelClaude to use models of anthropic ([#30](https://github.com/AIGNE-io/aigne-framework/issues/30)) ([0a62a64](https://github.com/AIGNE-io/aigne-framework/commit/0a62a6499e3da723a4646e67952051708ce7de6a))
+* **core:** add support for subscribing topics for agent memory ([#28](https://github.com/AIGNE-io/aigne-framework/issues/28)) ([eeecc67](https://github.com/AIGNE-io/aigne-framework/commit/eeecc67049a60ebcc4cdba0fbcd987b3d81f4af6))
+* **prompt-builder:** support chat history in PromptBuilder ([6ca05f2](https://github.com/AIGNE-io/aigne-framework/commit/6ca05f28eddb683a4f1e228865f8bbf8a8e190f1))
+* support run puppeteer example chat loop in terminal ([85ce7f8](https://github.com/AIGNE-io/aigne-framework/commit/85ce7f8de8b443c86e50815dd7bcab99f869c4ce))
+* use PromptBuilder instead of string instructions ([e4cb2cb](https://github.com/AIGNE-io/aigne-framework/commit/e4cb2cb6baf4f9bcef390567a4a174e9246c29a3))
+
+
+### Bug Fixes
+
+* **AIAgent:** should pass both arguments (model generated) and input (user input) to tool ([c49d64e](https://github.com/AIGNE-io/aigne-framework/commit/c49d64ee35f7efd83b0f82f43205bb1c40f999e8))
+* **core:** enforce stricter input/output type checks ([#26](https://github.com/AIGNE-io/aigne-framework/issues/26)) ([ef8cf53](https://github.com/AIGNE-io/aigne-framework/commit/ef8cf53586aff08a809909c56ab2a20f215fa129))
+* **MCP:** catch list resource error treat as empty list ([1885fab](https://github.com/AIGNE-io/aigne-framework/commit/1885fab3585e0dd1467b127e5b47cd0b98282bab))
+* rename @aigne/core-next to @aigne/core ([3a81009](https://github.com/AIGNE-io/aigne-framework/commit/3a8100962c81813217b687ae28e8de604419c622))
+* use text resource from MCP correctly ([8b9eba8](https://github.com/AIGNE-io/aigne-framework/commit/8b9eba83352ec096a2a5d4f410d4c4bde7420bce))
+
 ## [1.2.0](https://github.com/AIGNE-io/aigne-framework/compare/core-next-v1.1.0...core-next-v1.2.0) (2025-03-18)
 
 - chore: release v1.2.0

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

@@ -1,8 +1,10 @@
-import { inspect } from "node:util";
 import { ZodObject, type ZodType } from "zod";
-import type { Context } from "../aigne/context.js";
+import type { Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
-import type { MemoryAgent } from "../memory/memory.js";
+import type { Memory, MemoryAgent } from "../memory/memory.js";
+import type { MemoryRecorderInput } from "../memory/recorder.js";
+import type { MemoryRetrieverInput } from "../memory/retriever.js";
+import { nodejs } from "../utils/nodejs.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";
@@ -95,11 +97,29 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
 }>;
-export interface AgentInvokeOptions {
+export interface AgentInvokeOptions<U extends UserContext = UserContext> {
+    /**
+     * The execution context for the agent
+     *
+     * The context provides the runtime environment for agent execution, including:
+     * - Event emission and subscription management
+     * - Inter-agent communication and message passing
+     * - Resource usage tracking and limits enforcement
+     * - Timeout and status management
+     * - Memory and state management across agent invocations
+     *
+     * Each agent invocation requires a context to coordinate with the broader
+     * agent system and maintain proper isolation and resource control.
+     */
+    context: Context<U>;
     /**
      * Whether to enable streaming response
      *
@@ -111,6 +131,8 @@ export interface AgentInvokeOptions {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.
@@ -135,11 +157,24 @@ export interface AgentInvokeOptions {
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
 export declare abstract class Agent<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Custom object inspection behavior
+     *
+     * When using Node.js's util.inspect function to inspect an agent,
+     * only the agent's name will be shown, making output more concise
+     *
+     * @returns Agent name
+     */
+    [nodejs.customInspect]: () => string;
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
     /**
      * Lifecycle hooks for agent processing.
      *
@@ -278,11 +313,15 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
     /**
      * Check context status to ensure it hasn't timed out
      *
-     * @param context The context to check
+     * @param options Invocation options containing context
      * @throws Error if the context has timed out
      */
     private checkContextStatus;
     private newDefaultContext;
+    retrieveMemories(input: Pick<MemoryRetrieverInput, "limit"> & {
+        search?: Message | string;
+    }, options: Pick<AgentInvokeOptions, "context">): Promise<Pick<Memory, "content">[]>;
+    recordMemories(input: MemoryRecorderInput, options: Pick<AgentInvokeOptions, "context">): Promise<void>;
     /**
      * Invoke the agent with regular (non-streaming) response
      *
@@ -290,7 +329,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * suitable for scenarios where a complete result is needed at once.
      *
      * @param input Input message to the agent, can be a string or structured object
-     * @param context Execution context, providing environment and resource access
      * @param options Invocation options, must set streaming to false or leave unset
      * @returns Final JSON response
      *
@@ -298,7 +336,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with regular mode:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke}
      */
-    invoke(input: I | string, context?: Context, options?: AgentInvokeOptions & {
+    invoke(input: I | string, options?: Partial<AgentInvokeOptions> & {
         streaming?: false;
     }): Promise<O>;
     /**
@@ -309,7 +347,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * chat bot typing effects.
      *
      * @param input Input message to the agent, can be a string or structured object
-     * @param context Execution context, providing environment and resource access
      * @param options Invocation options, must set streaming to true for this overload
      * @returns Streaming response object
      *
@@ -317,7 +354,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with streaming response:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke-streaming}
      */
-    invoke(input: I | string, context: Context | undefined, options: {
+    invoke(input: I | string, options: Partial<AgentInvokeOptions> & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
     /**
@@ -326,12 +363,11 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Returns either streaming or regular response based on the streaming parameter in options
      *
      * @param input Input message to the agent
-     * @param context Execution context
      * @param options Invocation options
      * @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>;
+    invoke(input: I | string, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
      *
@@ -339,7 +375,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @param input Original input message
      * @param output Raw output produced by the agent
-     * @param context Execution context
+     * @param options Invocation options
      * @returns Final processed output
      */
     private processAgentOutput;
@@ -349,7 +385,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Logs error information, triggers failure events, and re-throws the error
      *
      * @param error Caught error
-     * @param context Execution context
+     * @param options Invocation options
      */
     private processAgentError;
     /**
@@ -358,10 +394,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * If the context has a maximum invocation limit set, checks if the limit
      * has been exceeded and increments the invocation counter
      *
-     * @param context Execution context
+     * @param options Invocation options containing context and limits
      * @throws Error if maximum invocation limit is exceeded
      */
-    protected checkAgentInvokesUsage(context: Context): void;
+    protected checkAgentInvokesUsage(options: AgentInvokeOptions): void;
     /**
      * Pre-processing operations before handling input
      *
@@ -370,9 +406,9 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * - Verifying invocation limits
      *
      * @param _ Input message (unused)
-     * @param context Execution context
+     * @param options Options for agent invocation
      */
-    protected preprocess(_: I, context: Context): PromiseOrValue<void>;
+    protected preprocess(_: I, options: AgentInvokeOptions): Promise<void>;
     private checkResponseByGuideRails;
     private runGuideRails;
     /**
@@ -400,10 +436,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @param input Input message
      * @param output Output message
-     * @param context Execution context
+     * @param options Options for agent invocation
      */
-    protected postprocess(input: I, output: O, context: Context): PromiseOrValue<void>;
-    protected publishToTopics(output: Message, context: Context): Promise<void>;
+    protected postprocess(input: I, output: O, options: AgentInvokeOptions): Promise<void>;
+    protected publishToTopics(output: Message, options: AgentInvokeOptions): Promise<void>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
      *
@@ -415,7 +451,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * - Another agent instance (transfer agent)
      *
      * @param input Input message
-     * @param context Execution context
+     * @param options Options for agent invocation
      * @returns Processing result
      *
      * @example
@@ -434,7 +470,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Example of transfer to another agent:
      * {@includeCode ../../test/agents/agent.test.ts#example-process-transfer}
      */
-    abstract process(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    abstract process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
     /**
      * Shut down the agent and clean up resources
      *
@@ -449,15 +485,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     shutdown(): Promise<void>;
-    /**
-     * Custom object inspection behavior
-     *
-     * When using Node.js's util.inspect function to inspect an agent,
-     * only the agent's name will be shown, making output more concise
-     *
-     * @returns Agent name
-     */
-    [inspect.custom](): string;
     /**
      * Async dispose method for shutdown the agent
      *
@@ -484,6 +511,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the input message
      */
     onStart?: (event: {
+        context: Context;
         input: I;
     }) => PromiseOrValue<void>;
     /**
@@ -496,6 +524,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the input message and either output or error
      */
     onEnd?: (event: XOr<{
+        context: Context;
         input: I;
         output: O;
         error: Error;
@@ -509,6 +538,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the skill being used and input message
      */
     onSkillStart?: (event: {
+        context: Context;
         skill: Agent;
         input: I;
     }) => PromiseOrValue<void>;
@@ -522,6 +552,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the skill used, input message, and either output or error
      */
     onSkillEnd?: (event: XOr<{
+        context: Context;
         skill: Agent;
         input: I;
         output: O;
@@ -537,6 +568,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the source agent, target agent, and input message
      */
     onHandoff?: (event: {
+        context: Context;
         source: Agent;
         target: Agent;
         input: I;
@@ -587,7 +619,7 @@ export interface AgentResponseDelta<T> {
         }> | Partial<{
             [key: string]: string;
         }>;
-        json?: Partial<T | TransferAgentOutput>;
+        json?: Partial<T> | TransferAgentOutput;
     };
 }
 /**
@@ -619,7 +651,7 @@ export declare function jsonDelta<T extends Message>(jsonDelta: NonNullable<Agen
  *
  * @template O Agent output message type
  */
-export type AgentProcessAsyncGenerator<O extends Message> = AsyncGenerator<AgentResponseChunk<O>, Partial<O | TransferAgentOutput> | undefined | void>;
+export type AgentProcessAsyncGenerator<O extends Message> = AsyncGenerator<AgentResponseChunk<O>, Partial<O> | TransferAgentOutput | undefined | void>;
 /**
  * Result type for agent processing method, can be:
  * - Direct or streaming response
@@ -709,10 +741,10 @@ export declare class FunctionAgent<I extends Message = Message, O extends Messag
      * Process input implementation, calls the configured processing function
      *
      * @param input Input message
-     * @param context Execution context
+     * @param options Invocation options
      * @returns Processing result
      */
-    process(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
 }
 /**
  * Function type for function agents
@@ -725,4 +757,4 @@ export declare class FunctionAgent<I extends Message = Message, O extends Messag
  * @param context Execution context
  * @returns Processing result, can be synchronous or asynchronous
  */
-export type FunctionAgentFn<I extends Message = any, O extends Message = any> = (input: I, context: Context) => PromiseOrValue<AgentProcessResult<O>>;
+export type FunctionAgentFn<I extends Message = any, O extends Message = any> = (input: I, options: AgentInvokeOptions) => PromiseOrValue<AgentProcessResult<O>>;