@aigne/core 1.29.1 → 1.32.0

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

@@ -1,16 +1,30 @@
+import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
+export interface FormatOptions {
+    workingDir?: string;
+}
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
     constructor(template: string);
-    format(variables?: Record<string, unknown>): string;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<string>;
+}
+export declare class CustomLoader extends nunjucks.Loader {
+    options: {
+        workingDir: string;
+    };
+    constructor(options: {
+        workingDir: string;
+    });
+    async: boolean;
+    getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {
     role: "system" | "user" | "agent" | "tool";
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
     static from(content: string, name?: string): SystemMessageTemplate;
@@ -22,19 +36,19 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
-    };
+    }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
     static from(content: object | string, toolCallId: string, name?: string): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
@@ -47,12 +61,12 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
             };
         }[];
         name?: string;
-    };
+    }>;
 }
 export declare class ChatMessagesTemplate {
     messages: ChatMessageTemplate[];
     static from(messages: ChatMessageTemplate[] | string): ChatMessagesTemplate;
     constructor(messages: ChatMessageTemplate[]);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage[];
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
 export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

package/lib/cjs/prompt/template.js

@@ -3,10 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.PromptTemplate = void 0;
+exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.CustomLoader = exports.PromptTemplate = void 0;
 exports.parseChatMessages = parseChatMessages;
-const mustache_1 = __importDefault(require("mustache"));
+const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
+const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_1 = require("zod");
+const type_utils_js_1 = require("../utils/type-utils.js");
+nunjucks_1.default.runtime.suppressValue = (v) => {
+    if ((0, type_utils_js_1.isNil)(v))
+        return "";
+    return typeof v === "object" ? JSON.stringify(v) : v;
+};
 class PromptTemplate {
     template;
     static from(template) {
@@ -15,15 +22,46 @@ class PromptTemplate {
     constructor(template) {
         this.template = template;
     }
-    format(variables) {
-        return mustache_1.default.render(this.template, variables, undefined, {
-            escape: (v) => {
-                return typeof v === "object" ? JSON.stringify(v) : v;
-            },
-        });
+    async format(variables = {}, options) {
+        let env = new nunjucks_1.default.Environment();
+        if (options?.workingDir) {
+            env = new nunjucks_1.default.Environment(new CustomLoader({ workingDir: options.workingDir }));
+        }
+        return new Promise((resolve, reject) => env.renderString(this.template, variables, (err, res) => {
+            if (err || !res) {
+                reject(err || new Error(`Failed to render template: ${this.template}`));
+            }
+            else {
+                resolve(res);
+            }
+        }));
     }
 }
 exports.PromptTemplate = PromptTemplate;
+class CustomLoader extends nunjucks_1.default.Loader {
+    options;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    async = true;
+    getSource(name, callback) {
+        let result = null;
+        index_js_1.nodejs.fs.readFile(index_js_1.nodejs.path.join(this.options.workingDir, name), "utf-8").then((content) => {
+            result = {
+                src: content,
+                path: name,
+                noCache: true,
+            };
+            callback(null, result);
+        }, (error) => {
+            callback(error, null);
+        });
+        // nunjucks expects return LoaderSource synchronously, but we handle it asynchronously.
+        return result;
+    }
+}
+exports.CustomLoader = CustomLoader;
 class ChatMessageTemplate {
     role;
     content;
@@ -33,17 +71,17 @@ class ChatMessageTemplate {
         this.content = content;
         this.name = name;
     }
-    format(variables) {
+    async format(variables, options) {
         let { content } = this;
         if (Array.isArray(content)) {
-            content = content.map((i) => {
+            content = await Promise.all(content.map(async (i) => {
                 if (i.type === "text")
-                    return { ...i, text: PromptTemplate.from(i.text).format(variables) };
+                    return { ...i, text: await PromptTemplate.from(i.text).format(variables, options) };
                 return i;
-            });
+            }));
         }
         else if (typeof content === "string") {
-            content = PromptTemplate.from(content).format(variables);
+            content = await PromptTemplate.from(content).format(variables, options);
         }
         return {
             role: this.role,
@@ -74,9 +112,9 @@ class AgentMessageTemplate extends ChatMessageTemplate {
         super("agent", content, name);
         this.toolCalls = toolCalls;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCalls: this.toolCalls,
         };
     }
@@ -93,9 +131,9 @@ class ToolMessageTemplate extends ChatMessageTemplate {
             : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
         this.toolCallId = toolCallId;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCallId: this.toolCallId,
         };
     }
@@ -109,8 +147,8 @@ class ChatMessagesTemplate {
     constructor(messages) {
         this.messages = messages;
     }
-    format(variables) {
-        return this.messages.map((message) => message.format(variables));
+    async format(variables, options) {
+        return Promise.all(this.messages.map((message) => message.format(variables, options)));
     }
 }
 exports.ChatMessagesTemplate = ChatMessagesTemplate;

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

@@ -1,4 +1,4 @@
-import { type ListPromptsResult, type ListResourceTemplatesResult, type ListResourcesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ListPromptsResult, type ListResourcesResult, type ListResourceTemplatesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
 import { type MCPBaseOptions, MCPPrompt, MCPResource, MCPTool } from "../agents/mcp-agent.js";
 export declare function toolFromMCPTool(tool: ListToolsResult["tools"][number], options: MCPBaseOptions): MCPTool;
 export declare function promptFromMCPPrompt(prompt: ListPromptsResult["prompts"][number], options: MCPBaseOptions): MCPPrompt;

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

@@ -21,6 +21,9 @@ const agent_js_1 = require("../agents/agent.js");
 const type_utils_js_1 = require("./type-utils.js");
 require("./stream-polyfill.js");
 function objectToAgentResponseStream(json) {
+    if (!(0, type_utils_js_1.isRecord)(json)) {
+        throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof json}): ${json}`);
+    }
     return new ReadableStream({
         pull(controller) {
             controller.enqueue({ delta: { json } });

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

@@ -0,0 +1,14 @@
+import { type AgentResponseChunk } from "../agents/agent.js";
+import type { ChatModelOutput } from "../agents/chat-model.js";
+export declare class ExtractMetadataTransform extends TransformStream<AgentResponseChunk<ChatModelOutput>, AgentResponseChunk<ChatModelOutput & {
+    metadata?: string;
+}>> {
+    private buffer;
+    private cursor;
+    private state;
+    constructor({ start, end, parse, }: {
+        start: string;
+        end: string;
+        parse: (raw: string) => object;
+    });
+}

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

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractMetadataTransform = void 0;
+const agent_js_1 = require("../agents/agent.js");
+class ExtractMetadataTransform extends TransformStream {
+    buffer = "";
+    cursor = 0;
+    state = "none";
+    constructor({ start, end, parse, }) {
+        super({
+            transform: async (chunk, controller) => {
+                if ((0, agent_js_1.isAgentResponseDelta)(chunk) && chunk.delta.text?.text) {
+                    const text = chunk.delta.text.text;
+                    this.buffer += text;
+                    for (;;) {
+                        if (this.state === "none") {
+                            const found = findMatchIndex(this.buffer, this.cursor, start);
+                            if (found.start > this.cursor) {
+                                const text = this.buffer.slice(this.cursor, found.start);
+                                this.cursor = found.start;
+                                controller.enqueue({ delta: { text: { text } } });
+                            }
+                            if (found.end) {
+                                this.state = "start";
+                                this.cursor = found.end;
+                            }
+                        }
+                        if (this.state === "start") {
+                            const found = findMatchIndex(this.buffer, this.cursor, end);
+                            if (found.end) {
+                                const metadata = this.buffer.slice(this.cursor, found.start);
+                                const json = parse(metadata);
+                                controller.enqueue({ delta: { json: { json } } });
+                                this.state = "none";
+                                this.cursor = found.end;
+                                continue;
+                            }
+                        }
+                        break;
+                    }
+                    return;
+                }
+                controller.enqueue(chunk);
+            },
+        });
+    }
+}
+exports.ExtractMetadataTransform = ExtractMetadataTransform;
+function findMatchIndex(str, position, match) {
+    const i = str.indexOf(match, position);
+    if (i >= 0)
+        return { start: i, end: i + match.length };
+    for (let i = match.length - 1; i > 0; i--) {
+        const m = match.slice(0, i);
+        if (str.endsWith(m)) {
+            return { start: str.length - m.length };
+        }
+    }
+    return { start: str.length };
+}

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

@@ -19,7 +19,7 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, ...key
 export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: (K | K[])[]): Omit<T, K>;
 export declare function omitDeep<T, K>(obj: T, ...keys: (K | K[])[]): unknown;
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
-export declare function orArrayToArray<T>(value?: T | T[]): T[];
+export declare function flat<T>(value?: T | T[]): T[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };

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

@@ -12,7 +12,7 @@ exports.pick = pick;
 exports.omit = omit;
 exports.omitDeep = omitDeep;
 exports.omitBy = omitBy;
-exports.orArrayToArray = orArrayToArray;
+exports.flat = flat;
 exports.createAccessorArray = createAccessorArray;
 exports.checkArguments = checkArguments;
 exports.tryOrThrow = tryOrThrow;
@@ -55,7 +55,7 @@ function duplicates(arr, key = (item) => item) {
 function remove(arr, remove) {
     const removed = [];
     for (let i = 0; i < arr.length; i++) {
-        // biome-ignore lint/style/noNonNullAssertion: <explanation>
+        // biome-ignore lint/style/noNonNullAssertion: false positive
         const item = arr[i];
         if ((Array.isArray(remove) && remove.includes(item)) ||
             (typeof remove === "function" && remove(item))) {
@@ -102,7 +102,7 @@ function omitBy(obj, predicate) {
         return !predicate(value, k);
     }));
 }
-function orArrayToArray(value) {
+function flat(value) {
     if (isNil(value))
         return [];
     return Array.isArray(value) ? value : [value];

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

@@ -137,8 +137,6 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
-    userContext?: U;
-    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.

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

@@ -50,6 +50,48 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default true
      */
     catchToolsError?: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   instructions: "Output metadata in JSON format at the end of response in markdown code block with json language",
+     *   metadataStart: "```json",
+     *   metadataEnd: "```",
+     *   parse: JSON.parse
+     * }
+     * ```
+     */
+    customStructuredStreamInstructions?: {
+        instructions: string | PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Whether to include memory agents as tools for the AI model
      *
@@ -217,6 +259,38 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default true
      */
     catchToolsError: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     */
+    customStructuredStreamInstructions?: {
+        instructions: PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Process an input message and generate a response
      *

package/lib/dts/aigne/context.d.ts

@@ -54,11 +54,15 @@ export interface InvokeOptions<U extends UserContext = UserContext> extends Part
      * @default true
      */
     newContext?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * @hidden
  */
 export interface UserContext extends Record<string, unknown> {
+    userId?: string;
+    sessionId?: string;
 }
 /**
  * @hidden

package/lib/dts/aigne/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./context.js";
 export * from "./aigne.js";
+export * from "./context.js";
 export * from "./message-queue.js";
 export * from "./usage.js";

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

@@ -5,8 +5,9 @@ import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
 }
-export interface PromptBuildOptions extends Pick<AgentInvokeOptions, "context"> {
+export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -15,11 +16,14 @@ export interface PromptBuildOptions extends Pick<AgentInvokeOptions, "context">
 export declare class PromptBuilder {
     static from(instructions: string | {
         path: string;
-    } | GetPromptResult): PromptBuilder;
+    } | GetPromptResult, { workingDir }?: {
+        workingDir?: string;
+    }): PromptBuilder;
     private static fromFile;
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;

package/lib/dts/prompt/prompts/memory-message-template.d.ts

@@ -1 +1 @@
-export declare const MEMORY_MESSAGE_TEMPLATE = "Here are some useful memories to consider:\n\n<memories>\n{{memories}}\n</memories>\n";
+export declare const MEMORY_MESSAGE_TEMPLATE = "<related-memories>\n{{memories}}\n</related-memories>\n";

package/lib/dts/prompt/prompts/structured-stream-instructions.d.ts

@@ -0,0 +1,7 @@
+import { parse } from "yaml";
+export declare const STRUCTURED_STREAM_INSTRUCTIONS: {
+    instructions: string;
+    metadataStart: string;
+    metadataEnd: string;
+    parse: typeof parse;
+};

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

@@ -1,16 +1,30 @@
+import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
+export interface FormatOptions {
+    workingDir?: string;
+}
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
     constructor(template: string);
-    format(variables?: Record<string, unknown>): string;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<string>;
+}
+export declare class CustomLoader extends nunjucks.Loader {
+    options: {
+        workingDir: string;
+    };
+    constructor(options: {
+        workingDir: string;
+    });
+    async: boolean;
+    getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {
     role: "system" | "user" | "agent" | "tool";
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
     static from(content: string, name?: string): SystemMessageTemplate;
@@ -22,19 +36,19 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
-    };
+    }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
     static from(content: object | string, toolCallId: string, name?: string): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
@@ -47,12 +61,12 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
             };
         }[];
         name?: string;
-    };
+    }>;
 }
 export declare class ChatMessagesTemplate {
     messages: ChatMessageTemplate[];
     static from(messages: ChatMessageTemplate[] | string): ChatMessagesTemplate;
     constructor(messages: ChatMessageTemplate[]);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage[];
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
 export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

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

@@ -1,4 +1,4 @@
-import { type ListPromptsResult, type ListResourceTemplatesResult, type ListResourcesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ListPromptsResult, type ListResourcesResult, type ListResourceTemplatesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
 import { type MCPBaseOptions, MCPPrompt, MCPResource, MCPTool } from "../agents/mcp-agent.js";
 export declare function toolFromMCPTool(tool: ListToolsResult["tools"][number], options: MCPBaseOptions): MCPTool;
 export declare function promptFromMCPPrompt(prompt: ListPromptsResult["prompts"][number], options: MCPBaseOptions): MCPPrompt;

package/lib/dts/utils/structured-stream-extractor.d.ts

@@ -0,0 +1,14 @@
+import { type AgentResponseChunk } from "../agents/agent.js";
+import type { ChatModelOutput } from "../agents/chat-model.js";
+export declare class ExtractMetadataTransform extends TransformStream<AgentResponseChunk<ChatModelOutput>, AgentResponseChunk<ChatModelOutput & {
+    metadata?: string;
+}>> {
+    private buffer;
+    private cursor;
+    private state;
+    constructor({ start, end, parse, }: {
+        start: string;
+        end: string;
+        parse: (raw: string) => object;
+    });
+}

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

@@ -19,7 +19,7 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, ...key
 export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: (K | K[])[]): Omit<T, K>;
 export declare function omitDeep<T, K>(obj: T, ...keys: (K | K[])[]): unknown;
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
-export declare function orArrayToArray<T>(value?: T | T[]): T[];
+export declare function flat<T>(value?: T | T[]): T[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };

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

@@ -137,8 +137,6 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
-    userContext?: U;
-    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.

package/lib/esm/agents/agent.js

@@ -2,7 +2,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { ZodObject, z } from "zod";
 import { logger } from "../utils/logger.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, isAsyncGenerator, objectToAgentResponseStream, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
-import { checkArguments, createAccessorArray, isEmpty, orArrayToArray, } from "../utils/type-utils.js";
+import { checkArguments, createAccessorArray, flat, isEmpty, isRecord, } from "../utils/type-utils.js";
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
 export * from "./types.js";
 export const agentOptionsSchema = z.object({
@@ -222,7 +222,7 @@ export class Agent {
         this.subscribeToTopics(context);
     }
     subscribeToTopics(context) {
-        for (const topic of orArrayToArray(this.subscribeTopic).concat(this.topic)) {
+        for (const topic of flat(this.subscribeTopic).concat(this.topic)) {
             this.subscriptions.push(context.subscribe(topic, (payload) => this.onMessage(payload)));
         }
     }
@@ -291,14 +291,6 @@ export class Agent {
             ...options,
             context: options.context ?? (await this.newDefaultContext()),
         };
-        if (options.userContext) {
-            Object.assign(opts.context.userContext, options.userContext);
-            options.userContext = undefined;
-        }
-        if (options.memories?.length) {
-            opts.context.memories.push(...options.memories);
-            options.memories = undefined;
-        }
         logger.debug("Invoke agent %s started with input: %O", this.name, input);
         if (!this.disableEvents)
             opts.context.emit("agentStarted", { agent: this, input });
@@ -357,6 +349,9 @@ export class Agent {
      */
     async processAgentOutput(input, output, options) {
         const { context } = options;
+        if (!isRecord(output)) {
+            throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
+        }
         const parsedOutput = checkArguments(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
         await this.postprocess(input, finalOutput, options);