@aigne/core 1.6.0 → 1.8.0

package/lib/esm/agents/agent.js

@@ -1,3 +1,4 @@
+import { inspect } from "node:util";
 import { ZodObject, z } from "zod";
 import { createMessage } from "../prompt/prompt-builder.js";
 import { logger } from "../utils/logger.js";
@@ -19,7 +20,7 @@ export class Agent {
         this.publishTopic = options.publishTopic;
         if (options.tools?.length)
             this.tools.push(...options.tools.map(functionToAgent));
-        this.disableLogging = options.disableLogging;
+        this.disableEvents = options.disableEvents;
         if (options.memory) {
             this.memory =
                 options.memory instanceof AgentMemory
@@ -56,7 +57,7 @@ export class Agent {
     subscribeTopic;
     publishTopic;
     tools = createAccessorArray([], (arr, name) => arr.find((t) => t.name === name));
-    disableLogging;
+    disableEvents;
     /**
      * Attach agent to context:
      * - subscribe to topic and call process method when message received
@@ -71,7 +72,7 @@ export class Agent {
                     await context.call(this, message);
                 }
                 catch (error) {
-                    context.emit("error", error);
+                    context.emit("agentFailed", { agent: this, error });
                 }
             });
         }
@@ -95,31 +96,45 @@ export class Agent {
     }
     async call(input, context) {
         const ctx = context ?? (await this.newDefaultContext());
-        const _input = typeof input === "string" ? createMessage(input) : input;
-        const parsedInput = this.inputSchema.parse(_input);
-        logger.debug("Call agent %s start with input: %O", this.name, input);
-        this.preprocess(parsedInput, ctx);
-        this.checkContextStatus(ctx);
-        const result = this.process(parsedInput, ctx)
-            .then((output) => {
-            const parsedOutput = this.outputSchema.parse(output);
-            return this.includeInputInOutput ? { ...parsedInput, ...parsedOutput } : parsedOutput;
-        })
-            .then((output) => {
-            this.postprocess(parsedInput, output, ctx);
+        const message = typeof input === "string" ? createMessage(input) : input;
+        logger.core("Call agent %s started with input: %O", this.name, input);
+        if (!this.disableEvents)
+            ctx.emit("agentStarted", { agent: this, input: message });
+        try {
+            const parsedInput = this.inputSchema.parse(message);
+            this.preprocess(parsedInput, ctx);
+            this.checkContextStatus(ctx);
+            const output = await this.process(parsedInput, ctx)
+                .then((output) => {
+                const parsedOutput = this.outputSchema.parse(output);
+                return this.includeInputInOutput ? { ...parsedInput, ...parsedOutput } : parsedOutput;
+            })
+                .then((output) => {
+                this.postprocess(parsedInput, output, ctx);
+                return output;
+            });
+            logger.core("Call agent %s succeed with output: %O", this.name, input);
+            if (!this.disableEvents)
+                ctx.emit("agentSucceed", { agent: this, output });
             return output;
-        });
-        return logger.debug.spinner(result, `Call agent ${this.name}`, (output) => logger.debug("Call agent %s succeed with output: %O", this.name, replaceTransferAgentToName(output)), { disabled: this.disableLogging });
+        }
+        catch (error) {
+            logger.core("Call agent %s failed with error: %O", this.name, error);
+            if (!this.disableEvents)
+                ctx.emit("agentFailed", { agent: this, error });
+            throw error;
+        }
+    }
+    checkUsageAgentCalls(context) {
+        const { limits, usage } = context;
+        if (limits?.maxAgentCalls && usage.agentCalls >= limits.maxAgentCalls) {
+            throw new Error(`Exceeded max agent calls ${usage.agentCalls}/${limits.maxAgentCalls}`);
+        }
+        usage.agentCalls++;
     }
     preprocess(_, context) {
         this.checkContextStatus(context);
-        if (context) {
-            const { limits, usage } = context;
-            if (limits?.maxAgentCalls && usage.agentCalls >= limits.maxAgentCalls) {
-                throw new Error(`Exceeded max agent calls ${usage.agentCalls}/${limits.maxAgentCalls}`);
-            }
-            usage.agentCalls++;
-        }
+        this.checkUsageAgentCalls(context);
     }
     postprocess(input, output, context) {
         this.checkContextStatus(context);
@@ -133,6 +148,9 @@ export class Agent {
     async shutdown() {
         this.memory?.detach();
     }
+    [inspect.custom]() {
+        return this.name;
+    }
 }
 function checkAgentInputOutputSchema(schema) {
     if (!(schema instanceof ZodObject) && typeof schema !== "function") {

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

@@ -28,6 +28,10 @@ export declare const aiAgentOptionsSchema: z.ZodObject<{
     memory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodAny, z.ZodAny]>>;
 }, "strip", z.ZodTypeAny, {
     description?: string | undefined;
+    memory?: any;
+    includeInputInOutput?: boolean | undefined;
+    subscribeTopic?: string | string[] | undefined;
+    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
     tools?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
     toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
     name?: string | undefined;
@@ -36,13 +40,13 @@ export declare const aiAgentOptionsSchema: z.ZodObject<{
     outputKey?: string | undefined;
     enableHistory?: boolean | undefined;
     maxHistoryMessages?: number | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
     disableLogging?: boolean | undefined;
-    memory?: any;
 }, {
     description?: string | undefined;
+    memory?: any;
+    includeInputInOutput?: boolean | undefined;
+    subscribeTopic?: string | string[] | undefined;
+    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
     tools?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
     toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
     name?: string | undefined;
@@ -51,11 +55,7 @@ export declare const aiAgentOptionsSchema: z.ZodObject<{
     outputKey?: string | undefined;
     enableHistory?: boolean | undefined;
     maxHistoryMessages?: number | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
     disableLogging?: boolean | undefined;
-    memory?: any;
 }>;
 export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     static from<I extends Message, O extends Message>(options: AIAgentOptions<I, O>): AIAgent<I, O>;

package/lib/esm/agents/ai-agent.js

@@ -59,7 +59,10 @@ export class AIAgent extends Agent {
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         const toolCallMessages = [];
         for (;;) {
-            const { text, json, toolCalls } = await model.call({ ...modelInput, messages: messages.concat(toolCallMessages) }, context);
+            const { text, json, toolCalls } = await context.call(model, {
+                ...modelInput,
+                messages: messages.concat(toolCallMessages),
+            });
             if (toolCalls?.length) {
                 const executedToolCalls = [];
                 // Execute tools
@@ -68,7 +71,7 @@ export class AIAgent extends Agent {
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
                     // NOTE: should pass both arguments (model generated) and input (user provided) to the tool
-                    const output = await tool.call({ ...call.function.arguments, ...input }, context);
+                    const output = await context.call(tool, { ...call.function.arguments, ...input }, { disableTransfer: true });
                     // NOTE: Return transfer output immediately
                     if (isTransferAgentOutput(output)) {
                         return output;

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

@@ -1,4 +1,5 @@
 import { Client, type ClientOptions } from "@modelcontextprotocol/sdk/client/index.js";
+import { type SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
 import { type StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
 import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
@@ -15,6 +16,15 @@ export interface MCPAgentOptions extends AgentOptions {
 export type MCPServerOptions = SSEServerParameters | StdioServerParameters;
 export type SSEServerParameters = {
     url: string;
+    /**
+     * Additional options to pass to the SSEClientTransport.
+     */
+    opts?: SSEClientTransportOptions;
+    /**
+     * The timeout for requests to the server, in milliseconds.
+     * @default 60000
+     */
+    timeout?: number;
     /**
      * Whether to automatically reconnect to the server if the connection is lost.
      * @default 10 set to 0 to disable automatic reconnection
@@ -31,7 +41,7 @@ export declare class MCPAgent extends Agent {
     static from(options: MCPAgentOptions): MCPAgent;
     private static fromTransport;
     constructor(options: MCPAgentOptions);
-    private client;
+    client: Client;
     readonly prompts: MCPPrompt[] & {
         [key: string]: MCPPrompt;
     };
@@ -44,6 +54,7 @@ export declare class MCPAgent extends Agent {
 }
 export interface ClientWithReconnectOptions {
     transportCreator?: () => PromiseOrValue<Transport>;
+    timeout?: number;
     maxReconnects?: number;
     shouldReconnect?: (error: Error) => boolean;
 }
@@ -60,7 +71,6 @@ export interface MCPBaseOptions<I extends Message = Message, O extends Message =
 export declare abstract class MCPBase<I extends Message, O extends Message> extends Agent<I, O> {
     constructor(options: MCPBaseOptions<I, O>);
     protected client: ClientWithReconnect;
-    protected get mcpServer(): string | undefined;
 }
 export declare class MCPTool extends MCPBase<Message, CallToolResult> {
     process(input: Message): Promise<CallToolResult>;

package/lib/esm/agents/mcp-agent.js

@@ -1,5 +1,5 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { SSEClientTransport, } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { UriTemplate } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
 import pRetry from "p-retry";
@@ -11,7 +11,11 @@ import { Agent } from "./agent.js";
 const MCP_AGENT_CLIENT_NAME = "MCPAgent";
 const MCP_AGENT_CLIENT_VERSION = "0.0.1";
 const DEFAULT_MAX_RECONNECTS = 10;
-const debug = logger.base.extend("mcp");
+const DEFAULT_TIMEOUT = () => z.coerce
+    .number()
+    .int()
+    .min(0)
+    .safeParse(process.env.MCP_TIMEOUT || process.env.TIMEOUT).data || 60e3;
 function isSSEServerParameters(options) {
     return "url" in options && typeof options.url === "string";
 }
@@ -31,7 +35,7 @@ export class MCPAgent extends Agent {
     static from(options) {
         checkArguments("MCPAgent.from", mcpAgentOptionsSchema, options);
         if (isSSEServerParameters(options)) {
-            const transport = () => new SSEClientTransport(new URL(options.url));
+            const transport = () => new SSEClientTransport(new URL(options.url), options.opts);
             return MCPAgent.fromTransport(transport, options);
         }
         if (isStdioServerParameters(options)) {
@@ -53,29 +57,36 @@ export class MCPAgent extends Agent {
             version: MCP_AGENT_CLIENT_VERSION,
         }, undefined, isSSEServerParameters(options) ? { transportCreator, ...options } : undefined);
         const transport = transportCreator();
-        await debug.spinner(client.connect(transport), `Connecting to MCP server: ${getMCPServerString(options)}`);
+        logger.mcp(`Connecting to MCP server: ${getMCPServerString(options)}`);
+        await client.connect(transport);
         const mcpServer = getMCPServerName(client);
         const { tools: isToolsAvailable, prompts: isPromptsAvailable, resources: isResourcesAvailable, } = client.getServerCapabilities() ?? {};
+        logger.mcp(`Listing tools from ${mcpServer}`);
         const tools = isToolsAvailable
-            ? await debug
-                .spinner(client.listTools(), `Listing tools from ${mcpServer}`, ({ tools }) => debug("%O", tools))
-                .then(({ tools }) => tools.map((tool) => toolFromMCPTool(tool, { client })))
+            ? await client.listTools().then(({ tools }) => {
+                logger.mcp(`Listing tools from ${mcpServer} completed %O`, tools?.map((i) => i.name));
+                return tools.map((tool) => toolFromMCPTool(tool, { client }));
+            })
             : undefined;
+        logger.mcp(`Listing prompts from ${mcpServer}`);
         const prompts = isPromptsAvailable
-            ? await debug
-                .spinner(client.listPrompts(), `Listing prompts from ${mcpServer}`, ({ prompts }) => debug("%O", prompts))
-                .then(({ prompts }) => prompts.map((prompt) => promptFromMCPPrompt(prompt, { client })))
+            ? await client.listPrompts().then(({ prompts }) => {
+                logger.mcp(`Listing prompts from ${mcpServer} completed %O`, prompts?.map((i) => i.name));
+                return prompts.map((prompt) => promptFromMCPPrompt(prompt, { client }));
+            })
             : undefined;
+        logger.mcp(`Listing resources from ${mcpServer}`);
+        // TODO: should conditionally call listResourceTemplates based on the server capabilities
+        // but the capability is not correct in the current SDK version
         const resources = isResourcesAvailable
-            ? await debug
-                .spinner(
-            // TODO: should conditionally call listResourceTemplates based on the server capabilities
-            // but the capability is not correct in the current SDK version
-            Promise.all([
+            ? await Promise.all([
                 client.listResources().catch(() => ({ resources: [] })),
                 client.listResourceTemplates().catch(() => ({ resourceTemplates: [] })),
-            ]), `Listing resources from ${mcpServer}`, ([{ resources }, { resourceTemplates }]) => debug("%O\n%O", resources, resourceTemplates))
-                .then(([{ resources }, { resourceTemplates }]) => [...resources, ...resourceTemplates].map((resource) => resourceFromMCPResource(resource, { client })))
+            ]).then(([{ resources }, { resourceTemplates }]) => {
+                const result = [...resources, ...resourceTemplates].map((resource) => resourceFromMCPResource(resource, { client }));
+                logger.mcp(`Listing resources from ${mcpServer} completed %O`, result.map((i) => i.name));
+                return result;
+            })
             : undefined;
         return new MCPAgent({
             name: client.getServerVersion()?.name,
@@ -127,22 +138,28 @@ class ClientWithReconnect extends Client {
             throw new Error("reconnect requires a transportCreator");
         await pRetry(async () => {
             await this.close();
-            await this.connect(await transportCreator());
+            await this.connect(await transportCreator(), {
+                timeout: this.reconnectOptions?.timeout ?? DEFAULT_TIMEOUT(),
+            });
         }, {
             retries: this.reconnectOptions?.maxReconnects ?? DEFAULT_MAX_RECONNECTS,
             shouldRetry: this.shouldReconnect,
-            onFailedAttempt: (error) => debug("Reconnect attempt failed: %O", error),
+            onFailedAttempt: (error) => logger.mcp("Reconnect attempt failed: %O", error),
         });
     }
     async request(request, resultSchema, options) {
+        const mergedOptions = {
+            ...options,
+            timeout: options?.timeout ?? DEFAULT_TIMEOUT(),
+        };
         try {
-            return await super.request(request, resultSchema, options);
+            return await super.request(request, resultSchema, mergedOptions);
         }
         catch (error) {
             if (this.shouldReconnect(error)) {
-                debug("Error occurred, reconnecting to MCP server: %O", error);
+                logger.mcp("Error occurred, reconnecting to MCP server: %O", error);
                 await this.reconnect();
-                return await super.request(request, resultSchema, options);
+                return await super.request(request, resultSchema, mergedOptions);
             }
             throw error;
         }
@@ -154,19 +171,16 @@ export class MCPBase extends Agent {
         this.client = options.client;
     }
     client;
-    get mcpServer() {
-        return getMCPServerName(this.client);
-    }
 }
 export class MCPTool extends MCPBase {
     async process(input) {
-        const result = await debug.spinner(this.client.callTool({ name: this.name, arguments: input }), `Call tool ${this.name} from ${this.mcpServer}`, (output) => debug("input: %O\noutput: %O", input, output));
+        const result = await this.client.callTool({ name: this.name, arguments: input });
         return result;
     }
 }
 export class MCPPrompt extends MCPBase {
     async process(input) {
-        const result = await debug.spinner(this.client.getPrompt({ name: this.name, arguments: input }), `Get prompt ${this.name} from ${this.mcpServer}`, (output) => debug("input: %O\noutput: %O", input, output));
+        const result = await this.client.getPrompt({ name: this.name, arguments: input });
         return result;
     }
 }
@@ -178,7 +192,7 @@ export class MCPResource extends MCPBase {
     uri;
     async process(input) {
         const uri = new UriTemplate(this.uri).expand(input);
-        const result = await debug.spinner(this.client.readResource({ uri }), `Read resource ${this.name} from ${this.mcpServer}`, (output) => debug("input: %O\noutput: %O", input, output));
+        const result = await this.client.readResource({ uri });
         return result;
     }
 }
@@ -197,6 +211,10 @@ const mcpAgentOptionsSchema = z.union([
     }),
     z.object({
         url: z.string(),
+        opts: z.object({}).optional(),
+        timeout: z.number().optional(),
+        maxReconnects: z.number().optional(),
+        shouldReconnect: z.function().args(z.instanceof(Error)).returns(z.boolean()).optional(),
     }),
     z.object({
         command: z.string(),

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

@@ -1,26 +1,26 @@
 import { ReadableStream } from "node:stream/web";
-import type { Context } from "../execution-engine/context.js";
-import type { MessagePayload, MessageQueueListener, Unsubscribe } from "../execution-engine/message-queue.js";
+import { type Context, type Runnable } from "../execution-engine/context.js";
+import type { MessagePayload } from "../execution-engine/message-queue.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentOptions, type Message } from "./agent.js";
 export interface UserAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
     context: Context;
     process?: (input: I, context: Context) => PromiseOrValue<O>;
+    activeAgent?: Runnable;
 }
 export declare class UserAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     static from<I extends Message, O extends Message>(options: UserAgentOptions<I, O>): UserAgent<I, O>;
     constructor(options: UserAgentOptions<I, O>);
-    readonly context: Context;
-    private get ctx();
+    context: Context;
     private _process?;
+    private activeAgent?;
     call(input: string | I, context?: Context): Promise<O>;
     process(input: I, context: Context): Promise<O>;
-    publish(topic: string | string[], message: Message | string): void;
-    subscribe(topic: string, listener?: undefined): Promise<MessagePayload>;
-    subscribe(topic: string, listener: MessageQueueListener): Unsubscribe;
-    subscribe(topic: string, listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
-    unsubscribe(topic: string, listener: MessageQueueListener): void;
+    publish: Context["publish"];
+    subscribe: Context["subscribe"];
+    unsubscribe: Context["unsubscribe"];
     get stream(): ReadableStream<MessagePayload & {
         topic: string;
     }>;
+    protected checkUsageAgentCalls(_context: Context): void;
 }

package/lib/esm/agents/user-agent.js

@@ -1,4 +1,5 @@
 import { ReadableStream } from "node:stream/web";
+import { createPublishMessage } from "../execution-engine/context.js";
 import { orArrayToArray } from "../utils/type-utils.js";
 import { Agent } from "./agent.js";
 export class UserAgent extends Agent {
@@ -6,40 +7,46 @@ export class UserAgent extends Agent {
         return new UserAgent(options);
     }
     constructor(options) {
-        super({ ...options, disableLogging: true });
+        super({ ...options, disableEvents: true });
         this._process = options.process;
         this.context = options.context;
+        this.activeAgent = options.activeAgent;
     }
     context;
-    get ctx() {
-        if (!this.context)
-            throw new Error("UserAgent must have a context");
-        return this.context;
-    }
     _process;
+    activeAgent;
     call(input, context) {
+        if (!context)
+            this.context = this.context.newContext({ reset: true });
         return super.call(input, context ?? this.context);
     }
     async process(input, context) {
         if (this._process) {
             return this._process(input, context);
         }
+        if (this.activeAgent) {
+            const [output, agent] = await context.call(this.activeAgent, input, {
+                returnActiveAgent: true,
+            });
+            this.activeAgent = agent;
+            return output;
+        }
         const publicTopic = typeof this.publishTopic === "function" ? await this.publishTopic(input) : this.publishTopic;
         if (publicTopic?.length) {
-            context.publish(publicTopic, input, this);
+            context.publish(publicTopic, createPublishMessage(input, this));
             return {};
         }
         throw new Error("UserAgent must have a process function or a publishTopic");
     }
-    publish(topic, message) {
-        return this.ctx.publish(topic, message, this);
-    }
-    subscribe(topic, listener) {
-        return this.ctx.subscribe(topic, listener);
-    }
-    unsubscribe(topic, listener) {
-        this.ctx.unsubscribe(topic, listener);
-    }
+    publish = ((...args) => {
+        return this.context.publish(...args);
+    });
+    subscribe = ((...args) => {
+        return this.context.subscribe(...args);
+    });
+    unsubscribe = ((...args) => {
+        this.context.unsubscribe(...args);
+    });
     get stream() {
         let subscriptions = [];
         return new ReadableStream({
@@ -56,4 +63,7 @@ export class UserAgent extends Agent {
             },
         });
     }
+    checkUsageAgentCalls(_context) {
+        // ignore calls usage check for UserAgent
+    }
 }

package/lib/esm/execution-engine/context.d.ts

@@ -2,19 +2,36 @@ import EventEmitter from "node:events";
 import { Agent, type FunctionAgentFn, type Message } from "../agents/agent.js";
 import { UserAgent } from "../agents/user-agent.js";
 import type { ChatModel } from "../models/chat-model.js";
+import { type OmitPropertiesFromArrayFirstElement } from "../utils/type-utils.js";
+import type { Args, Listener, TypedEventEmitter } from "../utils/typed-event-emtter.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import { type ContextLimits, type ContextUsage } from "./usage.js";
 export type Runnable<I extends Message = Message, O extends Message = Message> = Agent<I, O> | FunctionAgentFn;
-export interface ContextUsage {
-    promptTokens: number;
-    completionTokens: number;
-    agentCalls: number;
+export interface AgentEvent {
+    parentContextId?: string;
+    contextId: string;
+    timestamp: number;
+    agent: Agent;
 }
-export interface ContextLimits {
-    maxTokens?: number;
-    maxAgentCalls?: number;
-    timeout?: number;
+export interface ContextEventMap {
+    agentStarted: [AgentEvent & {
+        input: Message;
+    }];
+    agentSucceed: [AgentEvent & {
+        output: Message;
+    }];
+    agentFailed: [AgentEvent & {
+        error: Error;
+    }];
 }
-export interface Context extends EventEmitter {
+export type ContextEmitEventMap = {
+    [K in keyof ContextEventMap]: OmitPropertiesFromArrayFirstElement<ContextEventMap[K], "contextId" | "parentContextId" | "timestamp">;
+};
+export interface CallOptions {
+    returnActiveAgent?: boolean;
+    disableTransfer?: boolean;
+}
+export interface Context extends TypedEventEmitter<ContextEventMap, ContextEmitEventMap> {
     model?: ChatModel;
     tools?: Agent[];
     usage: ContextUsage;
@@ -26,13 +43,6 @@ export interface Context extends EventEmitter {
      * @returns User agent
      */
     call<I extends Message, O extends Message>(agent: Runnable<I, O>): UserAgent<I, O>;
-    /**
-     * Call an agent with a message
-     * @param agent Agent to call
-     * @param message Message to pass to the agent
-     * @returns the output of the agent
-     */
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string): Promise<O>;
     /**
      * Call an agent with a message and return the output and the active agent
      * @param agent Agent to call
@@ -40,54 +50,82 @@ export interface Context extends EventEmitter {
      * @param options.returnActiveAgent return the active agent
      * @returns the output of the agent and the final active agent
      */
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string, options: {
+    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string, options: CallOptions & {
         returnActiveAgent: true;
     }): Promise<[O, Runnable]>;
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string, options?: {
-        returnActiveAgent?: boolean;
-    }): UserAgent<I, O> | Promise<O | [O, Runnable]>;
+    /**
+     * Call an agent with a message
+     * @param agent Agent to call
+     * @param message Message to pass to the agent
+     * @returns the output of the agent
+     */
+    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string, options?: CallOptions): Promise<O>;
+    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message?: I | string, options?: CallOptions): UserAgent<I, O> | Promise<O | [O, Runnable]>;
     /**
      * Publish a message to a topic, the engine will call the listeners of the topic
      * @param topic topic name, or an array of topic names
-     * @param message message to publish
-     * @param from the agent who publish the message, if not provided, it will be treated as a user message
+     * @param payload message to publish
      */
-    publish(topic: string | string[], message: Message | string, from?: Agent): void;
+    publish(topic: string | string[], payload: Omit<MessagePayload, "context">): void;
     subscribe(topic: string, listener?: undefined): Promise<MessagePayload>;
     subscribe(topic: string, listener: MessageQueueListener): Unsubscribe;
     subscribe(topic: string, listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
+    subscribe(topic: string, listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
     unsubscribe(topic: string, listener: MessageQueueListener): void;
+    /**
+     * Create a child context with the same configuration as the parent context.
+     * If `reset` is true, the child context will have a new state (such as: usage).
+     *
+     * @param options
+     * @param options.reset create a new context with initial state (such as: usage)
+     * @returns new context
+     */
+    newContext(options?: {
+        reset?: boolean;
+    }): Context;
+}
+export declare function createPublishMessage(message: string | Message, from?: Agent): Omit<MessagePayload, "context">;
+export declare class ExecutionContext implements Context {
+    constructor(parent?: ConstructorParameters<typeof ExecutionContextInternal>[0]);
+    parentId?: string;
+    id: string;
+    readonly internal: ExecutionContextInternal;
+    get model(): ChatModel | undefined;
+    get tools(): Agent<Message, Message>[] | undefined;
+    get limits(): ContextLimits | undefined;
+    get status(): "normal" | "timeout";
+    get usage(): ContextUsage;
+    newContext({ reset }?: {
+        reset?: boolean;
+    }): ExecutionContext;
+    call: Context["call"];
+    publish: Context["publish"];
+    subscribe: Context["subscribe"];
+    unsubscribe: Context["unsubscribe"];
+    emit<K extends keyof ContextEmitEventMap>(eventName: K, ...args: Args<K, ContextEmitEventMap>): boolean;
+    on<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
+    once<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
+    off<K extends keyof ContextEventMap>(eventName: K, listener: Listener<K, ContextEventMap>): this;
 }
-export declare class ExecutionContext extends EventEmitter implements Context {
-    private readonly engine?;
-    constructor(engine?: {
-        model?: ChatModel;
-        tools?: Agent[];
-        limits?: ContextLimits;
+declare class ExecutionContextInternal {
+    private readonly parent?;
+    constructor(parent?: (Pick<Context, "model" | "tools" | "limits"> & {
         messageQueue?: MessageQueue;
-        emit?: EventEmitter["emit"];
-    } | undefined);
-    private messageQueue;
+    }) | undefined);
+    readonly messageQueue: MessageQueue;
+    readonly events: EventEmitter<ContextEventMap>;
     get model(): ChatModel | undefined;
     get tools(): Agent<Message, Message>[] | undefined;
+    get limits(): ContextLimits | undefined;
     usage: ContextUsage;
-    limits?: ContextLimits | undefined;
     private abortController;
     private timer?;
     private initTimeout;
     get status(): "normal" | "timeout";
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>): UserAgent<I, O>;
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string): Promise<O>;
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message: I | string, options: {
-        returnActiveAgent: true;
-    }): Promise<[O, Runnable]>;
-    call<I extends Message, O extends Message>(agent: Runnable<I, O>, message?: I | string, options?: {
-        returnActiveAgent?: boolean;
-    }): UserAgent<I, O> | Promise<O | [O, Runnable]>;
-    publish(topic: string | string[], message: Message | string, from?: Agent): void;
-    subscribe(topic: string, listener?: undefined): Promise<MessagePayload>;
-    subscribe(topic: string, listener: MessageQueueListener): Unsubscribe;
-    unsubscribe(topic: string, listener: MessageQueueListener): void;
-    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+    call<I extends Message, O extends Message>(agent: Runnable<I, O>, input: I, context: Context, options?: CallOptions): Promise<{
+        agent: Runnable;
+        output: O;
+    }>;
     private callAgent;
 }
+export {};