@aigne/core 1.3.1 → 1.4.1-0

package/lib/dts/models/claude-chat-model.d.ts

@@ -1,16 +1,65 @@
 import Anthropic from "@anthropic-ai/sdk";
-import { ChatModel, type ChatModelInput, type ChatModelOutput } from "./chat-model.js";
-export declare class ClaudeChatModel extends ChatModel {
-    config?: {
-        apiKey?: string;
-        model?: string;
+import { z } from "zod";
+import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+export interface ClaudeChatModelOptions {
+    apiKey?: string;
+    model?: string;
+    modelOptions?: ChatModelOptions;
+}
+export declare const claudeChatModelOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    modelOptions: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        parallelToolCalls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    }, {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    modelOptions?: {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
     } | undefined;
-    constructor(config?: {
-        apiKey?: string;
-        model?: string;
-    } | undefined);
+    model?: string | undefined;
+    apiKey?: string | undefined;
+}, {
+    modelOptions?: {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    } | undefined;
+    model?: string | undefined;
+    apiKey?: string | undefined;
+}>;
+export declare class ClaudeChatModel extends ChatModel {
+    options?: ClaudeChatModelOptions | undefined;
+    constructor(options?: ClaudeChatModelOptions | undefined);
     private _client?;
     get client(): Anthropic;
+    get modelOptions(): ChatModelOptions | undefined;
     process(input: ChatModelInput): Promise<ChatModelOutput>;
     private extractResultFromClaudeStream;
     private requestStructuredOutput;

package/lib/dts/models/openai-chat-model.d.ts

@@ -1,14 +1,67 @@
-import { ChatModel, type ChatModelInput, type ChatModelOutput } from "./chat-model.js";
-export declare class OpenAIChatModel extends ChatModel {
-    config?: {
-        apiKey?: string;
-        model?: string;
+import { z } from "zod";
+import { ChatModel, type ChatModelInput, type ChatModelOptions, type ChatModelOutput } from "./chat-model.js";
+export interface OpenAIChatModelOptions {
+    apiKey?: string;
+    baseURL?: string;
+    model?: string;
+    modelOptions?: ChatModelOptions;
+}
+export declare const openAIChatModelOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    modelOptions: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        parallelToolCalls: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+    }, {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    modelOptions?: {
+        parallelToolCalls: boolean;
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
     } | undefined;
-    constructor(config?: {
-        apiKey?: string;
-        model?: string;
-    } | undefined);
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    baseURL?: string | undefined;
+}, {
+    modelOptions?: {
+        model?: string | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+        frequencyPenalty?: number | undefined;
+        presencePenalty?: number | undefined;
+        parallelToolCalls?: boolean | undefined;
+    } | undefined;
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    baseURL?: string | undefined;
+}>;
+export declare class OpenAIChatModel extends ChatModel {
+    options?: OpenAIChatModelOptions | undefined;
+    constructor(options?: OpenAIChatModelOptions | undefined);
     private _client?;
     private get client();
+    get modelOptions(): ChatModelOptions | undefined;
     process(input: ChatModelInput): Promise<ChatModelOutput>;
 }

package/lib/dts/models/xai-chat-model.d.ts

@@ -0,0 +1,12 @@
+import type { ChatModelOptions } from "./chat-model.js";
+import { OpenAIChatModel } from "./openai-chat-model.js";
+export interface XAIChatModelOptions {
+    apiKey?: string;
+    model?: string;
+    modelOptions?: ChatModelOptions;
+    baseURL?: string;
+}
+export declare class XAIChatModel extends OpenAIChatModel {
+    options?: XAIChatModelOptions | undefined;
+    constructor(options?: XAIChatModelOptions | undefined);
+}

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

@@ -1,5 +1,5 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import { Agent, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
 import type { AgentMemory } from "../agents/memory.js";
 import type { Context } from "../execution-engine/context.js";
@@ -18,7 +18,7 @@ export interface PromptBuilderBuildOptions {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
-    outputSchema?: AgentOptions["outputSchema"];
+    outputSchema?: Agent["outputSchema"];
 }
 export declare class PromptBuilder {
     static from(instructions: string): PromptBuilder;

package/lib/dts/utils/json-schema.d.ts

@@ -1,4 +1,12 @@
-import type { ZodType } from "zod";
+import type { ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function outputSchemaToResponseFormatSchema(agentOutput: ZodType<Message>): Record<string, unknown>;
 export declare function parseJSON(json: string): any;
+/**
+ * Ensure that the union array has at least 1 item.
+ * NOTE: the zod union requires at least 2 items (just type definition, not runtime behavior)
+ * so we need to ensure that the union has at least 1 item.
+ * @param union - The union array
+ * @returns The union array with at least 1 item (but the type is at least 2 items for z.union)
+ */
+export declare function ensureZodUnionArray<T extends z.ZodType>(union: T[]): [T, T, ...T[]];

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

@@ -1,3 +1,4 @@
+import { type ZodType } from "zod";
 export type PromiseOrValue<T> = T | Promise<T>;
 export type Nullish<T> = T | null | undefined;
 export declare function isNonNullable<T>(value: T): value is NonNullable<T>;
@@ -9,3 +10,4 @@ export declare function get(obj: unknown, path: string | string[], type: "number
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };
+export declare function checkArguments<T>(prefix: string, schema: ZodType<T>, args: T): void;

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

@@ -11,8 +11,8 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
     publishTopic?: PublishTopic<O>;
     name?: string;
     description?: string;
-    inputSchema?: ZodType<I>;
-    outputSchema?: ZodType<O>;
+    inputSchema?: AgentInputOutputSchema<I>;
+    outputSchema?: AgentInputOutputSchema<O>;
     includeInputInOutput?: boolean;
     tools?: (Agent | FunctionAgentFn)[];
     disableLogging?: boolean;
@@ -27,8 +27,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      */
     get topic(): string;
     readonly description?: string;
-    readonly inputSchema: ZodType<I>;
-    readonly outputSchema: ZodType<O>;
+    private readonly _inputSchema?;
+    private readonly _outputSchema?;
+    get inputSchema(): ZodType<I>;
+    get outputSchema(): ZodType<O>;
     readonly includeInputInOutput?: boolean;
     readonly subscribeTopic?: SubscribeTopic;
     readonly publishTopic?: PublishTopic<Message>;
@@ -49,6 +51,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
     abstract process(input: I, context?: Context): Promise<O | TransferAgentOutput>;
     shutdown(): Promise<void>;
 }
+export type AgentInputOutputSchema<I extends Message = Message> = ZodType<I> | ((agent: Agent) => ZodType<I>);
 export interface FunctionAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
     fn?: FunctionAgentFn<I, O>;
 }

package/lib/esm/agents/agent.js

@@ -8,12 +8,12 @@ export class Agent {
     constructor({ inputSchema, outputSchema, ...options }) {
         this.name = options.name || this.constructor.name;
         this.description = options.description;
-        if ((inputSchema && !(inputSchema instanceof ZodObject)) ||
-            (outputSchema && !(outputSchema instanceof ZodObject))) {
-            throw new Error("inputSchema must be a Zod object");
-        }
-        this.inputSchema = (inputSchema || z.object({})).passthrough();
-        this.outputSchema = (outputSchema || z.object({})).passthrough();
+        if (inputSchema)
+            checkAgentInputOutputSchema(inputSchema);
+        if (outputSchema)
+            checkAgentInputOutputSchema(outputSchema);
+        this._inputSchema = inputSchema;
+        this._outputSchema = outputSchema;
         this.includeInputInOutput = options.includeInputInOutput;
         this.subscribeTopic = options.subscribeTopic;
         this.publishTopic = options.publishTopic;
@@ -38,8 +38,20 @@ export class Agent {
         return `$agent_${this.name}`;
     }
     description;
-    inputSchema;
-    outputSchema;
+    _inputSchema;
+    _outputSchema;
+    get inputSchema() {
+        const s = this._inputSchema;
+        const schema = typeof s === "function" ? s(this) : s || z.object({});
+        checkAgentInputOutputSchema(schema);
+        return schema.passthrough();
+    }
+    get outputSchema() {
+        const s = this._outputSchema;
+        const schema = typeof s === "function" ? s(this) : s || z.object({});
+        checkAgentInputOutputSchema(schema);
+        return schema.passthrough();
+    }
     includeInputInOutput;
     subscribeTopic;
     publishTopic;
@@ -94,6 +106,11 @@ export class Agent {
         this.memory?.detach();
     }
 }
+function checkAgentInputOutputSchema(schema) {
+    if (!(schema instanceof ZodObject) && typeof schema !== "function") {
+        throw new Error("schema must be a zod object or function return a zod object ");
+    }
+}
 export class FunctionAgent extends Agent {
     static from(options) {
         return typeof options === "function" ? functionToAgent(options) : new FunctionAgent(options);

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

@@ -1,5 +1,6 @@
+import { z } from "zod";
 import type { Context } from "../execution-engine/context.js";
-import type { ChatModel } from "../models/chat-model.js";
+import { ChatModel } from "../models/chat-model.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentOptions, type Message } from "./agent.js";
 export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
@@ -9,6 +10,53 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
     toolChoice?: AIAgentToolChoice;
 }
 export type AIAgentToolChoice = "auto" | "none" | "required" | "router" | Agent;
+export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>;
+export declare const aiAgentOptionsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodType<ChatModel, z.ZodTypeDef, ChatModel>>;
+    instructions: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodType<PromptBuilder, z.ZodTypeDef, PromptBuilder>]>>;
+    outputKey: z.ZodOptional<z.ZodString>;
+    toolChoice: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>>;
+    enableHistory: z.ZodOptional<z.ZodBoolean>;
+    maxHistoryMessages: z.ZodOptional<z.ZodNumber>;
+    includeInputInOutput: z.ZodOptional<z.ZodBoolean>;
+    subscribeTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    publishTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>, "many">>;
+    disableLogging: z.ZodOptional<z.ZodBoolean>;
+    memory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodAny, z.ZodAny]>>;
+}, "strip", z.ZodTypeAny, {
+    tools?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
+    toolChoice?: "auto" | "none" | "required" | Agent<Message, Message> | "router" | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    model?: ChatModel | undefined;
+    instructions?: string | PromptBuilder | undefined;
+    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;
+}, {
+    tools?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
+    toolChoice?: "auto" | "none" | "required" | Agent<Message, Message> | "router" | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    model?: ChatModel | undefined;
+    instructions?: string | PromptBuilder | undefined;
+    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>;
     constructor(options: AIAgentOptions<I, O>);

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

@@ -1,12 +1,38 @@
+import { z } from "zod";
+import { ChatModel } from "../models/chat-model.js";
 import { MESSAGE_KEY, PromptBuilder } from "../prompt/prompt-builder.js";
 import { AgentMessageTemplate, ToolMessageTemplate } from "../prompt/template.js";
 import { Agent } from "./agent.js";
 import { isTransferAgentOutput } from "./types.js";
+export const aiAgentToolChoiceSchema = z.union([
+    z.literal("auto"),
+    z.literal("none"),
+    z.literal("required"),
+    z.literal("router"),
+    z.instanceof(Agent),
+], { message: "aiAgentToolChoice must be 'auto', 'none', 'required', 'router', or an Agent" });
+export const aiAgentOptionsSchema = z.object({
+    model: z.instanceof(ChatModel).optional(),
+    instructions: z.union([z.string(), z.instanceof(PromptBuilder)]).optional(),
+    outputKey: z.string().optional(),
+    toolChoice: aiAgentToolChoiceSchema.optional(),
+    enableHistory: z.boolean().optional(),
+    maxHistoryMessages: z.number().optional(),
+    includeInputInOutput: z.boolean().optional(),
+    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
+    publishTopic: z.union([z.string(), z.array(z.string()), z.function()]).optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    tools: z.array(z.union([z.instanceof(Agent), z.function()])).optional(),
+    disableLogging: z.boolean().optional(),
+    memory: z.union([z.boolean(), z.any(), z.any()]).optional(),
+});
 export class AIAgent extends Agent {
     static from(options) {
         return new AIAgent(options);
     }
     constructor(options) {
+        aiAgentOptionsSchema.parse(options);
         super(options);
         this.model = options.model;
         this.instructions =

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

@@ -2,9 +2,10 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.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 { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { promptFromMCPPrompt, resourceFromMCPResource, toolFromMCPTool, } from "../utils/mcp-utils.js";
-import { createAccessorArray } from "../utils/type-utils.js";
+import { checkArguments, createAccessorArray } from "../utils/type-utils.js";
 import { Agent } from "./agent.js";
 const MCP_AGENT_CLIENT_NAME = "MCPAgent";
 const MCP_AGENT_CLIENT_VERSION = "0.0.1";
@@ -15,11 +16,21 @@ function isSSEServerParameters(options) {
 function isStdioServerParameters(options) {
     return "command" in options && typeof options.command === "string";
 }
+function getMCPServerString(options) {
+    if (isSSEServerParameters(options)) {
+        return options.url;
+    }
+    if (isStdioServerParameters(options)) {
+        return `${options.command} ${options.args?.join(" ") || ""}`;
+    }
+    return "unknown";
+}
 export class MCPAgent extends Agent {
     static from(options) {
+        checkArguments("MCPAgent.from", mcpAgentOptionsSchema, options);
         if (isSSEServerParameters(options)) {
             const transport = new SSEClientTransport(new URL(options.url));
-            return MCPAgent.fromTransport(transport);
+            return MCPAgent.fromTransport(transport, options);
         }
         if (isStdioServerParameters(options)) {
             const transport = new StdioClientTransport({
@@ -30,16 +41,16 @@ export class MCPAgent extends Agent {
                 },
                 stderr: "pipe",
             });
-            return MCPAgent.fromTransport(transport);
+            return MCPAgent.fromTransport(transport, options);
         }
         return new MCPAgent(options);
     }
-    static async fromTransport(transport) {
+    static async fromTransport(transport, options) {
         const client = new Client({
             name: MCP_AGENT_CLIENT_NAME,
             version: MCP_AGENT_CLIENT_VERSION,
         });
-        await debug.spinner(client.connect(transport), "Connecting to MCP server");
+        await debug.spinner(client.connect(transport), `Connecting to MCP server: ${getMCPServerString(options)}`);
         const mcpServer = getMCPServerName(client);
         const { tools: isToolsAvailable, prompts: isPromptsAvailable, resources: isResourcesAvailable, } = client.getServerCapabilities() ?? {};
         const tools = isToolsAvailable
@@ -134,3 +145,18 @@ function getMCPServerName(client) {
     const { name, version } = info;
     return `${name}@${version}`;
 }
+const mcpAgentOptionsSchema = z.union([
+    z.object({
+        client: z.instanceof(Client),
+        prompts: z.array(z.instanceof(MCPPrompt)).optional(),
+        resources: z.array(z.instanceof(MCPResource)).optional(),
+    }),
+    z.object({
+        url: z.string(),
+    }),
+    z.object({
+        command: z.string(),
+        args: z.array(z.string()).optional(),
+        env: z.record(z.string()).optional(),
+    }),
+]);

package/lib/esm/agents/memory.js

@@ -1,6 +1,8 @@
-import { orArrayToArray } from "../utils/type-utils.js";
+import { z } from "zod";
+import { checkArguments, orArrayToArray } from "../utils/type-utils.js";
 export class AgentMemory {
     constructor(options) {
+        checkArguments("AgentMemory", agentMemoryOptionsSchema, options);
         this.enabled = options.enabled ?? true;
         this.subscribeTopic = options.subscribeTopic;
         this.maxMemoriesInChat = options.maxMemoriesInChat;
@@ -32,3 +34,8 @@ export class AgentMemory {
         this.subscriptions = [];
     }
 }
+const agentMemoryOptionsSchema = z.object({
+    enabled: z.boolean().optional(),
+    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
+    maxMemoriesInChat: z.number().optional(),
+});

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

@@ -1,7 +1,7 @@
 import EventEmitter from "node:events";
 import { Agent, type Message } from "../agents/agent.js";
 import { UserAgent } from "../agents/user-agent.js";
-import type { ChatModel } from "../models/chat-model.js";
+import { ChatModel } from "../models/chat-model.js";
 import type { Context, Runnable } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
 export interface ExecutionEngineOptions {

package/lib/esm/execution-engine/execution-engine.js

@@ -1,12 +1,17 @@
 import EventEmitter from "node:events";
 import { isNil } from "lodash-es";
+import { z } from "zod";
 import { Agent } from "../agents/agent.js";
 import { isTransferAgentOutput, transferAgentOutputKey } from "../agents/types.js";
 import { UserAgent } from "../agents/user-agent.js";
+import { ChatModel } from "../models/chat-model.js";
 import { createMessage } from "../prompt/prompt-builder.js";
+import { checkArguments } from "../utils/type-utils.js";
 import { MessageQueue, } from "./message-queue.js";
 export class ExecutionEngine extends EventEmitter {
     constructor(options) {
+        if (options)
+            checkArguments("ExecutionEngine", executionEngineOptionsSchema, options);
         super();
         this.model = options?.model;
         this.tools = options?.tools ?? [];
@@ -19,6 +24,7 @@ export class ExecutionEngine extends EventEmitter {
     tools;
     agents = [];
     addAgent(...agents) {
+        checkArguments("ExecutionEngine.addAgent", executionEngineAddAgentArgsSchema, agents);
         for (const agent of agents) {
             this.agents.push(agent);
             agent.attach(this);
@@ -34,6 +40,11 @@ export class ExecutionEngine extends EventEmitter {
      * @param from the agent who publish the message, if not provided, it will be treated as a user message
      */
     publish(topic, message, from) {
+        checkArguments("ExecutionEngine.publish", executionEnginePublishArgsSchema, {
+            topic,
+            message,
+            from,
+        });
         const request = {
             role: !from || from instanceof UserAgent ? "user" : "agent",
             source: from?.name,
@@ -42,6 +53,11 @@ export class ExecutionEngine extends EventEmitter {
         this.messageQueue.publish(topic, request);
     }
     call(agent, message, options) {
+        checkArguments("ExecutionEngine.call", executionEngineCallArgsSchema, {
+            agent,
+            message,
+            options,
+        });
         if (isNil(message)) {
             let activeAgent = agent;
             return UserAgent.from({
@@ -76,9 +92,17 @@ export class ExecutionEngine extends EventEmitter {
         return { output, agent: activeAgent };
     }
     subscribe(topic, listener) {
+        checkArguments("ExecutionEngine.subscribe", executionEngineSubscribeArgsSchema, {
+            topic,
+            listener,
+        });
         return this.messageQueue.subscribe(topic, listener);
     }
     unsubscribe(topic, listener) {
+        checkArguments("ExecutionEngine.unsubscribe", executionEngineUnsubscribeArgsSchema, {
+            topic,
+            listener,
+        });
         this.messageQueue.unsubscribe(topic, listener);
     }
     async callAgent(agent, input) {
@@ -127,3 +151,27 @@ export class ExecutionEngine extends EventEmitter {
         process.on("exit", shutdownAndExit);
     }
 }
+const executionEngineOptionsSchema = z.object({
+    model: z.instanceof(ChatModel).optional(),
+    tools: z.array(z.instanceof(Agent)).optional(),
+    agents: z.array(z.instanceof(Agent)).optional(),
+});
+const executionEngineAddAgentArgsSchema = z.array(z.instanceof(Agent));
+const executionEnginePublishArgsSchema = z.object({
+    topic: z.union([z.string(), z.array(z.string())]),
+    message: z.union([z.string(), z.record(z.unknown())]),
+    from: z.instanceof(Agent).optional(),
+});
+const executionEngineCallArgsSchema = z.object({
+    agent: z.union([z.function(), z.instanceof(Agent)]),
+    message: z.union([z.record(z.unknown()), z.string()]).optional(),
+    options: z.object({ returnActiveAgent: z.boolean().optional() }).optional(),
+});
+const executionEngineSubscribeArgsSchema = z.object({
+    topic: z.string(),
+    listener: z.function(z.tuple([z.any()]), z.any()).optional(),
+});
+const executionEngineUnsubscribeArgsSchema = z.object({
+    topic: z.string(),
+    listener: z.function(z.tuple([z.any()]), z.any()),
+});

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

@@ -1,4 +1,4 @@
-import type { FunctionAgentFn } from "../agents/agent.js";
+import { type FunctionAgentFn } from "../agents/agent.js";
 import type { Runnable } from "./context.js";
 export declare function sequential(..._agents: [Runnable, ...Runnable[]]): FunctionAgentFn;
 export declare function parallel(..._agents: [Runnable, ...Runnable[]]): FunctionAgentFn;

package/lib/esm/execution-engine/utils.js

@@ -1,4 +1,8 @@
+import { z } from "zod";
+import { Agent } from "../agents/agent.js";
+import { checkArguments } from "../utils/type-utils.js";
 export function sequential(..._agents) {
+    checkArguments("sequential", agentArraySchema, _agents);
     let agents = [..._agents];
     return async (input, context) => {
         if (!context)
@@ -16,6 +20,7 @@ export function sequential(..._agents) {
     };
 }
 export function parallel(..._agents) {
+    checkArguments("parallel", agentArraySchema, _agents);
     let agents = [..._agents];
     return async (input, context) => {
         if (!context)
@@ -26,3 +31,4 @@ export function parallel(..._agents) {
         return Object.assign({}, ...outputs);
     };
 }
+const agentArraySchema = z.array(z.union([z.function(), z.instanceof(Agent)]));

package/lib/esm/index.d.ts

@@ -8,7 +8,10 @@ export * from "./execution-engine/index.js";
 export * from "./models/chat-model.js";
 export * from "./models/claude-chat-model.js";
 export * from "./models/openai-chat-model.js";
+export * from "./models/xai-chat-model.js";
 export * from "./prompt/prompt-builder.js";
 export * from "./prompt/template.js";
+export * from "./utils/json-schema.js";
 export * from "./utils/logger.js";
 export * from "./utils/run-chat-loop.js";
+export * from "./utils/type-utils.js";

package/lib/esm/index.js

@@ -8,7 +8,10 @@ export * from "./execution-engine/index.js";
 export * from "./models/chat-model.js";
 export * from "./models/claude-chat-model.js";
 export * from "./models/openai-chat-model.js";
+export * from "./models/xai-chat-model.js";
 export * from "./prompt/prompt-builder.js";
 export * from "./prompt/template.js";
+export * from "./utils/json-schema.js";
 export * from "./utils/logger.js";
 export * from "./utils/run-chat-loop.js";
+export * from "./utils/type-utils.js";

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

@@ -65,6 +65,7 @@ export interface ChatModelOptions {
     topP?: number;
     frequencyPenalty?: number;
     presencePenalty?: number;
+    parallelToolCalls?: boolean;
 }
 export interface ChatModelOutput extends Message {
     text?: string;