@aigne/core 1.72.0-beta.6 → 1.72.0-beta.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.72.0-beta.7](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.72.0-beta.6...core-v1.72.0-beta.7) (2025-12-26)
+
+
+### Features
+
+* **core:** add session history support ([#858](https://github.com/AIGNE-io/aigne-framework/issues/858)) ([28a070e](https://github.com/AIGNE-io/aigne-framework/commit/28a070ed33b821d1fd344b899706d817ca992b9f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0-beta.4
+    * @aigne/afs-history bumped to 1.2.0-beta.4
+
 ## [1.72.0-beta.6](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.72.0-beta.5...core-v1.72.0-beta.6) (2025-12-25)
 
 

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

@@ -9,7 +9,7 @@ import type { Memory, MemoryAgent } from "../memory/memory.js";
 import type { MemoryRecorderInput } from "../memory/recorder.js";
 import type { MemoryRetrieverInput } from "../memory/retriever.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
-import type { ChatModel } from "./chat-model.js";
+import type { ChatModel, ChatModelInputMessage } from "./chat-model.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { ImageModel } from "./image-model.js";
 import { type GetterSchema, type TransferAgentOutput } from "./types.js";
@@ -350,7 +350,20 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     private disableEvents?;
     historyConfig?: {
-        disabled?: boolean;
+        /**
+         * Whether to enable history recording and injection
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Whether to record history entries, default to enabled when history is enabled
+         */
+        record?: boolean;
+        /**
+         * Whether to inject history entries into the context, default to enabled when history is enabled
+         */
+        inject?: boolean;
+        useOldMemory?: boolean;
         maxTokens?: number;
         maxItems?: number;
     };
@@ -455,7 +468,9 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @param options Invocation options
      * @returns Final processed output
      */
-    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, options: AgentInvokeOptions): Promise<O>;
+    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, { messages, ...options }: AgentInvokeOptions & {
+        messages?: ChatModelInputMessage[];
+    }): Promise<O>;
     /**
      * Process errors that occur during agent execution
      *
@@ -785,29 +800,29 @@ export interface AgentResponseProgress {
         error: Error;
     } | {
         event: "message";
-        role: "user" | "agent";
-        message: ({
-            type: "text";
-            content: string;
-        } | {
-            type: "thinking";
-            thoughts: string;
-        } | {
-            type: "tool_use";
-            toolUseId: string;
-            name: string;
-            input: unknown;
-        } | {
-            type: "tool_result";
-            toolUseId: string;
-            content: unknown;
-        })[];
+        message: ChatModelInputMessage;
     }) & Omit<AgentEvent, "agent"> & {
         agent: {
             name: string;
         };
     };
 }
+export type AgentResponseProgressMessageItem = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    thoughts: string;
+} | {
+    type: "tool_use";
+    toolUseId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: unknown;
+};
 export declare function isAgentResponseProgress<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseProgress;
 /**
  * Creates a text delta for streaming responses

package/lib/cjs/agents/agent.js

@@ -463,11 +463,15 @@ class Agent {
                     : (0, stream_utils_js_1.isAsyncGenerator)(response)
                         ? (0, stream_utils_js_1.asyncGeneratorToReadableStream)(response)
                         : (0, stream_utils_js_1.objectToAgentResponseStream)(response);
+                const messages = [];
                 for await (const chunk of stream) {
                     (0, stream_utils_js_1.mergeAgentResponseChunk)(output, chunk);
                     yield chunk;
+                    if (isAgentResponseProgress(chunk) && chunk.progress.event === "message") {
+                        messages.push(chunk.progress.message);
+                    }
                 }
-                let result = await this.processAgentOutput(input, output, options);
+                let result = await this.processAgentOutput(input, output, { ...options, messages });
                 if (attempt > 0) {
                     result = { ...result, $meta: { ...result.$meta, retries: attempt } };
                 }
@@ -564,7 +568,7 @@ class Agent {
      * @param options Invocation options
      * @returns Final processed output
      */
-    async processAgentOutput(input, output, options) {
+    async processAgentOutput(input, output, { messages, ...options }) {
         const { context } = options;
         if (!(0, type_utils_js_1.isRecord)(output)) {
             throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
@@ -576,8 +580,17 @@ class Agent {
         const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
-        if (this.historyConfig?.disabled !== true)
-            this.afs?.emit("agentSucceed", { input, output: finalOutput });
+        if (this.historyConfig?.record === true ||
+            (this.historyConfig?.record !== false && this.historyConfig?.enabled)) {
+            this.afs?.emit("agentSucceed", {
+                agentId: this.name,
+                userId: context.userContext.userId,
+                sessionId: context.userContext.sessionId,
+                input,
+                output: finalOutput,
+                messages,
+            });
+        }
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;

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

@@ -349,8 +349,10 @@ class AIAgent extends agent_js_1.Agent {
             yield {
                 progress: {
                     event: "message",
-                    role: "user",
-                    message: [{ type: "text", content: inputMessage }],
+                    message: {
+                        role: "user",
+                        content: [{ type: "text", text: inputMessage }],
+                    },
                 },
             };
         }
@@ -379,15 +381,22 @@ class AIAgent extends agent_js_1.Agent {
                 }
             }
             const { toolCalls, json, text, thoughts, files } = modelOutput;
-            if (text) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "text", content: text }] },
-                };
-            }
-            if (thoughts) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "thinking", thoughts }] },
-                };
+            if (text || thoughts) {
+                const content = [];
+                if (thoughts) {
+                    content.push({ type: "text", text: thoughts, isThinking: true });
+                }
+                if (text) {
+                    content.push({ type: "text", text });
+                }
+                if (content.length) {
+                    yield {
+                        progress: {
+                            event: "message",
+                            message: { role: "agent", content },
+                        },
+                    };
+                }
             }
             if (toolCalls?.length) {
                 if (this.keepTextInToolUses !== true) {
@@ -419,25 +428,14 @@ class AIAgent extends agent_js_1.Agent {
                         queue.killAndDrain();
                     }
                 }, this.toolCallsConcurrency || 1);
+                yield {
+                    progress: { event: "message", message: { role: "agent", toolCalls } },
+                };
                 // Execute tools
                 for (const call of toolCalls) {
                     const tool = toolsMap.get(call.function.name);
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
-                    yield {
-                        progress: {
-                            event: "message",
-                            role: "agent",
-                            message: [
-                                {
-                                    type: "tool_use",
-                                    name: call.function.name,
-                                    input: call.function.arguments,
-                                    toolUseId: call.id,
-                                },
-                            ],
-                        },
-                    };
                     queue.push({ tool, call });
                 }
                 await queue.drained();
@@ -449,14 +447,11 @@ class AIAgent extends agent_js_1.Agent {
                         yield {
                             progress: {
                                 event: "message",
-                                role: "agent",
-                                message: [
-                                    {
-                                        type: "tool_result",
-                                        toolUseId: call.id,
-                                        content: output,
-                                    },
-                                ],
+                                message: {
+                                    role: "tool",
+                                    toolCallId: call.id,
+                                    content: JSON.stringify(output),
+                                },
                             },
                         };
                     }
@@ -480,11 +475,6 @@ class AIAgent extends agent_js_1.Agent {
             if (!(0, type_utils_js_1.isEmpty)(result)) {
                 yield { delta: { json: result } };
             }
-            if (text) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "text", content: text }] },
-                };
-            }
             return;
         }
     }

package/lib/cjs/agents/chat-model.d.ts

@@ -225,6 +225,7 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    isThinking?: boolean;
     /**
      * Cache control marker (only supported by Claude)
      *

package/lib/cjs/loader/agent-yaml.d.ts

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, TaskRenderMode } from "../agents/agent.js";
+import type { Agent, AgentHooks, TaskRenderMode } from "../agents/agent.js";
 import type { LoadOptions } from "./index.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -65,6 +65,7 @@ export interface AgentSchema {
         context?: AFSContextSchema;
     });
     shareAFS?: boolean;
+    historyConfig?: Agent["historyConfig"];
     [key: string]: unknown;
 }
 export declare function parseAgentFile(path: string, data: any, options: LoadOptions): Promise<AgentSchema>;

package/lib/cjs/loader/agent-yaml.js

@@ -100,6 +100,14 @@ const getAgentSchema = ({ filepath }) => {
                 })),
             ])),
             shareAFS: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+            historyConfig: (0, schema_js_1.camelizeSchema)((0, schema_js_1.optionalize)(zod_1.z.object({
+                enabled: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                record: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                inject: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                use_old_memory: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                maxTokens: (0, schema_js_1.optionalize)(zod_1.z.number().int().positive()),
+                maxItems: (0, schema_js_1.optionalize)(zod_1.z.number().int().positive()),
+            }))),
         });
         return (0, schema_js_1.camelizeSchema)(baseAgentSchema.passthrough());
     });

package/lib/cjs/prompt/context/afs/history.d.ts

@@ -1,5 +1,9 @@
+import type { AFSListOptions } from "@aigne/afs";
 import type { Agent } from "../../../agents/agent.js";
-export declare function getHistories(agent: Agent): Promise<{
+export declare function getHistories({ filter, agent, }: {
+    filter: AFSListOptions["filter"];
+    agent: Agent;
+}): Promise<{
     role: "user" | "agent";
     content: unknown;
 }[]>;

package/lib/cjs/prompt/context/afs/history.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getHistories = getHistories;
 const afs_history_1 = require("@aigne/afs-history");
 const type_utils_js_1 = require("../../../utils/type-utils.js");
-async function getHistories(agent) {
+async function getHistories({ filter, agent, }) {
     const afs = agent?.afs;
     if (!afs)
         return [];
@@ -11,6 +11,7 @@ async function getHistories(agent) {
     if (!historyModule)
         return [];
     const history = (await afs.list(historyModule.path, {
+        filter,
         limit: agent.historyConfig?.maxItems || 10,
         orderBy: [["createdAt", "desc"]],
     })).data;

package/lib/cjs/prompt/context/afs/index.js

@@ -20,7 +20,14 @@ function createAFSContext(agent, context) {
         get histories() {
             if (!agent)
                 return Promise.resolve([]);
-            return (0, history_js_1.getHistories)(agent);
+            return (0, history_js_1.getHistories)({
+                agent,
+                filter: {
+                    agentId: agent.name,
+                    userId: context?.userContext.userId,
+                    sessionId: context?.userContext.sessionId,
+                },
+            });
         },
         get skills() {
             const afs = agent?.afs;

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

@@ -1,14 +1,16 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
+import { Agent, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
-import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import { type ChatModel, type ChatModelInput, type ChatModelInputMessage } from "../agents/chat-model.js";
 import { type FileUnionContent } from "../agents/model.js";
+import type { Context } from "../aigne/context.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
 }
-export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
+export interface PromptBuildOptions {
+    context?: Context;
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -37,10 +39,12 @@ export declare class PromptBuilder {
     }>;
     private getTemplateVariables;
     private buildMessages;
-    getHistories(options: PromptBuildOptions): Promise<{
-        role: "user" | "agent";
-        content: unknown;
-    }[]>;
+    protected deprecatedMemories(message: string | undefined, options: PromptBuildOptions): Promise<ChatModelInputMessage[]>;
+    getHistories({ agentId, userId, sessionId, ...options }: PromptBuildOptions & {
+        agentId?: string;
+        userId?: string;
+        sessionId?: string;
+    }): Promise<ChatModelInputMessage[]>;
     private refineMessages;
     private convertMemoriesToMessages;
     private buildResponseFormat;

package/lib/cjs/prompt/prompt-builder.js

@@ -8,6 +8,7 @@ const zod_1 = require("zod");
 const zod_to_json_schema_1 = require("zod-to-json-schema");
 const agent_js_1 = require("../agents/agent.js");
 const ai_agent_js_1 = require("../agents/ai-agent.js");
+const chat_model_js_1 = require("../agents/chat-model.js");
 const model_js_1 = require("../agents/model.js");
 const schema_js_1 = require("../loader/schema.js");
 const json_schema_js_1 = require("../utils/json-schema.js");
@@ -100,6 +101,9 @@ class PromptBuilder {
     }
     async buildMessages(options) {
         const { input } = options;
+        const agentId = options.agent?.name;
+        const userId = options.context?.userContext.userId;
+        const sessionId = options.context?.userContext.sessionId;
         const inputKey = options.agent?.inputKey;
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
         const [messages, otherCustomMessages] = (0, type_utils_js_1.partition)((await (typeof this.instructions === "string"
@@ -109,6 +113,50 @@ class PromptBuilder {
         const files = (0, type_utils_js_1.flat)(inputFileKey
             ? (0, type_utils_js_1.checkArguments)("Check input files", (0, schema_js_1.optionalize)(model_js_1.fileUnionContentsSchema), input?.[inputFileKey])
             : null);
+        const historyConfig = options.agent?.historyConfig;
+        const injectHistory = historyConfig?.inject === true || (historyConfig?.inject !== false && historyConfig?.enabled);
+        if (injectHistory) {
+            if (historyConfig.useOldMemory) {
+                messages.push(...(await this.deprecatedMemories(message, options)));
+            }
+            else {
+                const history = await this.getHistories({ ...options, agentId, userId, sessionId });
+                messages.push(...history);
+            }
+        }
+        // if the agent is using structured stream mode, add the instructions
+        const { structuredStreamMode, outputSchema } = options.agent || {};
+        if (structuredStreamMode && outputSchema) {
+            const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
+                PromptBuilder.from(structured_stream_instructions_js_1.STRUCTURED_STREAM_INSTRUCTIONS.instructions);
+            messages.push(...(await instructions.buildMessages({
+                input: {
+                    ...input,
+                    outputJsonSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(outputSchema),
+                },
+            })));
+        }
+        messages.push(...otherCustomMessages);
+        if (message || files.length) {
+            const content = [];
+            if (message &&
+                // avoid duplicate user messages: developer may have already included the message in the messages
+                !otherCustomMessages.some((i) => i.role === "user" &&
+                    (typeof i.content === "string"
+                        ? i.content.includes(message)
+                        : i.content?.some((c) => c.type === "text" && c.text.includes(message))))) {
+                content.push({ type: "text", text: message });
+            }
+            if (files.length)
+                content.push(...files);
+            if (content.length) {
+                messages.push({ role: "user", content });
+            }
+        }
+        return this.refineMessages(options, messages);
+    }
+    async deprecatedMemories(message, options) {
+        const messages = [];
         const memories = [];
         if (options.agent && options.context) {
             memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
@@ -117,7 +165,7 @@ class PromptBuilder {
             memories.push(...options.context.memories);
         }
         const afs = options.agent?.afs;
-        if (afs && options.agent?.historyConfig?.disabled !== true) {
+        if (afs && options.agent?.historyConfig?.enabled) {
             const historyModule = (await afs.listModules()).find((m) => m.module instanceof afs_history_1.AFSHistory);
             if (historyModule) {
                 const history = await afs.list(historyModule.path, {
@@ -163,38 +211,9 @@ class PromptBuilder {
         }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
-        // if the agent is using structured stream mode, add the instructions
-        const { structuredStreamMode, outputSchema } = options.agent || {};
-        if (structuredStreamMode && outputSchema) {
-            const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
-                PromptBuilder.from(structured_stream_instructions_js_1.STRUCTURED_STREAM_INSTRUCTIONS.instructions);
-            messages.push(...(await instructions.buildMessages({
-                input: {
-                    ...input,
-                    outputJsonSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(outputSchema),
-                },
-            })));
-        }
-        if (message || files.length) {
-            const content = [];
-            if (message &&
-                // avoid duplicate user messages: developer may have already included the message in the custom user messages
-                !otherCustomMessages.some((i) => i.role === "user" &&
-                    (typeof i.content === "string"
-                        ? i.content.includes(message)
-                        : i.content?.some((c) => c.type === "text" && c.text.includes(message))))) {
-                content.push({ type: "text", text: message });
-            }
-            if (files.length)
-                content.push(...files);
-            if (content.length) {
-                messages.push({ role: "user", content });
-            }
-        }
-        messages.push(...otherCustomMessages);
-        return this.refineMessages(options, messages);
+        return messages;
     }
-    async getHistories(options) {
+    async getHistories({ agentId, userId, sessionId, ...options }) {
         const { agent } = options;
         const afs = agent?.afs;
         if (!afs)
@@ -203,24 +222,21 @@ class PromptBuilder {
         if (!historyModule)
             return [];
         const history = (await afs.list(historyModule.path, {
+            filter: { agentId, userId, sessionId },
             limit: agent.historyConfig?.maxItems || 10,
             orderBy: [["createdAt", "desc"]],
-        })).data;
-        return history
-            .reverse()
-            .map((i) => {
-            if (!i.content)
-                return;
-            const { input, output } = i.content;
-            if (!input || !output)
-                return;
-            return [
-                { role: "user", content: input },
-                { role: "agent", content: output },
-            ];
-        })
-            .filter(type_utils_js_1.isNonNullable)
-            .flat();
+        })).data.reverse();
+        return (await Promise.all(history.map(async (i) => {
+            if (Array.isArray(i.content?.messages) &&
+                i.content.messages.every((m) => chat_model_js_1.roleSchema.parse(m?.role))) {
+                return i.content.messages;
+            }
+            const { input, output } = i.content || {};
+            if (input && output) {
+                return await this.convertMemoriesToMessages([{ content: { input, output } }], options);
+            }
+            return [];
+        }))).flat();
     }
     refineMessages(options, messages) {
         const { autoReorderSystemMessages, autoMergeSystemMessages } = options.agent ?? {};

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

@@ -9,7 +9,7 @@ import type { Memory, MemoryAgent } from "../memory/memory.js";
 import type { MemoryRecorderInput } from "../memory/recorder.js";
 import type { MemoryRetrieverInput } from "../memory/retriever.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
-import type { ChatModel } from "./chat-model.js";
+import type { ChatModel, ChatModelInputMessage } from "./chat-model.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { ImageModel } from "./image-model.js";
 import { type GetterSchema, type TransferAgentOutput } from "./types.js";
@@ -350,7 +350,20 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     private disableEvents?;
     historyConfig?: {
-        disabled?: boolean;
+        /**
+         * Whether to enable history recording and injection
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Whether to record history entries, default to enabled when history is enabled
+         */
+        record?: boolean;
+        /**
+         * Whether to inject history entries into the context, default to enabled when history is enabled
+         */
+        inject?: boolean;
+        useOldMemory?: boolean;
         maxTokens?: number;
         maxItems?: number;
     };
@@ -455,7 +468,9 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @param options Invocation options
      * @returns Final processed output
      */
-    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, options: AgentInvokeOptions): Promise<O>;
+    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, { messages, ...options }: AgentInvokeOptions & {
+        messages?: ChatModelInputMessage[];
+    }): Promise<O>;
     /**
      * Process errors that occur during agent execution
      *
@@ -785,29 +800,29 @@ export interface AgentResponseProgress {
         error: Error;
     } | {
         event: "message";
-        role: "user" | "agent";
-        message: ({
-            type: "text";
-            content: string;
-        } | {
-            type: "thinking";
-            thoughts: string;
-        } | {
-            type: "tool_use";
-            toolUseId: string;
-            name: string;
-            input: unknown;
-        } | {
-            type: "tool_result";
-            toolUseId: string;
-            content: unknown;
-        })[];
+        message: ChatModelInputMessage;
     }) & Omit<AgentEvent, "agent"> & {
         agent: {
             name: string;
         };
     };
 }
+export type AgentResponseProgressMessageItem = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    thoughts: string;
+} | {
+    type: "tool_use";
+    toolUseId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: unknown;
+};
 export declare function isAgentResponseProgress<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseProgress;
 /**
  * Creates a text delta for streaming responses

package/lib/dts/agents/chat-model.d.ts

@@ -225,6 +225,7 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    isThinking?: boolean;
     /**
      * Cache control marker (only supported by Claude)
      *

package/lib/dts/loader/agent-yaml.d.ts

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, TaskRenderMode } from "../agents/agent.js";
+import type { Agent, AgentHooks, TaskRenderMode } from "../agents/agent.js";
 import type { LoadOptions } from "./index.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -65,6 +65,7 @@ export interface AgentSchema {
         context?: AFSContextSchema;
     });
     shareAFS?: boolean;
+    historyConfig?: Agent["historyConfig"];
     [key: string]: unknown;
 }
 export declare function parseAgentFile(path: string, data: any, options: LoadOptions): Promise<AgentSchema>;

package/lib/dts/prompt/context/afs/history.d.ts

@@ -1,5 +1,9 @@
+import type { AFSListOptions } from "@aigne/afs";
 import type { Agent } from "../../../agents/agent.js";
-export declare function getHistories(agent: Agent): Promise<{
+export declare function getHistories({ filter, agent, }: {
+    filter: AFSListOptions["filter"];
+    agent: Agent;
+}): Promise<{
     role: "user" | "agent";
     content: unknown;
 }[]>;

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

@@ -1,14 +1,16 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
+import { Agent, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
-import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import { type ChatModel, type ChatModelInput, type ChatModelInputMessage } from "../agents/chat-model.js";
 import { type FileUnionContent } from "../agents/model.js";
+import type { Context } from "../aigne/context.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
 }
-export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
+export interface PromptBuildOptions {
+    context?: Context;
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -37,10 +39,12 @@ export declare class PromptBuilder {
     }>;
     private getTemplateVariables;
     private buildMessages;
-    getHistories(options: PromptBuildOptions): Promise<{
-        role: "user" | "agent";
-        content: unknown;
-    }[]>;
+    protected deprecatedMemories(message: string | undefined, options: PromptBuildOptions): Promise<ChatModelInputMessage[]>;
+    getHistories({ agentId, userId, sessionId, ...options }: PromptBuildOptions & {
+        agentId?: string;
+        userId?: string;
+        sessionId?: string;
+    }): Promise<ChatModelInputMessage[]>;
     private refineMessages;
     private convertMemoriesToMessages;
     private buildResponseFormat;

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

@@ -9,7 +9,7 @@ import type { Memory, MemoryAgent } from "../memory/memory.js";
 import type { MemoryRecorderInput } from "../memory/recorder.js";
 import type { MemoryRetrieverInput } from "../memory/retriever.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
-import type { ChatModel } from "./chat-model.js";
+import type { ChatModel, ChatModelInputMessage } from "./chat-model.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { ImageModel } from "./image-model.js";
 import { type GetterSchema, type TransferAgentOutput } from "./types.js";
@@ -350,7 +350,20 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     private disableEvents?;
     historyConfig?: {
-        disabled?: boolean;
+        /**
+         * Whether to enable history recording and injection
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Whether to record history entries, default to enabled when history is enabled
+         */
+        record?: boolean;
+        /**
+         * Whether to inject history entries into the context, default to enabled when history is enabled
+         */
+        inject?: boolean;
+        useOldMemory?: boolean;
         maxTokens?: number;
         maxItems?: number;
     };
@@ -455,7 +468,9 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @param options Invocation options
      * @returns Final processed output
      */
-    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, options: AgentInvokeOptions): Promise<O>;
+    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, { messages, ...options }: AgentInvokeOptions & {
+        messages?: ChatModelInputMessage[];
+    }): Promise<O>;
     /**
      * Process errors that occur during agent execution
      *
@@ -785,29 +800,29 @@ export interface AgentResponseProgress {
         error: Error;
     } | {
         event: "message";
-        role: "user" | "agent";
-        message: ({
-            type: "text";
-            content: string;
-        } | {
-            type: "thinking";
-            thoughts: string;
-        } | {
-            type: "tool_use";
-            toolUseId: string;
-            name: string;
-            input: unknown;
-        } | {
-            type: "tool_result";
-            toolUseId: string;
-            content: unknown;
-        })[];
+        message: ChatModelInputMessage;
     }) & Omit<AgentEvent, "agent"> & {
         agent: {
             name: string;
         };
     };
 }
+export type AgentResponseProgressMessageItem = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    thoughts: string;
+} | {
+    type: "tool_use";
+    toolUseId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: unknown;
+};
 export declare function isAgentResponseProgress<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseProgress;
 /**
  * Creates a text delta for streaming responses

package/lib/esm/agents/agent.js

@@ -415,11 +415,15 @@ export class Agent {
                     : isAsyncGenerator(response)
                         ? asyncGeneratorToReadableStream(response)
                         : objectToAgentResponseStream(response);
+                const messages = [];
                 for await (const chunk of stream) {
                     mergeAgentResponseChunk(output, chunk);
                     yield chunk;
+                    if (isAgentResponseProgress(chunk) && chunk.progress.event === "message") {
+                        messages.push(chunk.progress.message);
+                    }
                 }
-                let result = await this.processAgentOutput(input, output, options);
+                let result = await this.processAgentOutput(input, output, { ...options, messages });
                 if (attempt > 0) {
                     result = { ...result, $meta: { ...result.$meta, retries: attempt } };
                 }
@@ -516,7 +520,7 @@ export class Agent {
      * @param options Invocation options
      * @returns Final processed output
      */
-    async processAgentOutput(input, output, options) {
+    async processAgentOutput(input, output, { messages, ...options }) {
         const { context } = options;
         if (!isRecord(output)) {
             throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
@@ -528,8 +532,17 @@ export class Agent {
         const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
-        if (this.historyConfig?.disabled !== true)
-            this.afs?.emit("agentSucceed", { input, output: finalOutput });
+        if (this.historyConfig?.record === true ||
+            (this.historyConfig?.record !== false && this.historyConfig?.enabled)) {
+            this.afs?.emit("agentSucceed", {
+                agentId: this.name,
+                userId: context.userContext.userId,
+                sessionId: context.userContext.sessionId,
+                input,
+                output: finalOutput,
+                messages,
+            });
+        }
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;

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

@@ -313,8 +313,10 @@ export class AIAgent extends Agent {
             yield {
                 progress: {
                     event: "message",
-                    role: "user",
-                    message: [{ type: "text", content: inputMessage }],
+                    message: {
+                        role: "user",
+                        content: [{ type: "text", text: inputMessage }],
+                    },
                 },
             };
         }
@@ -343,15 +345,22 @@ export class AIAgent extends Agent {
                 }
             }
             const { toolCalls, json, text, thoughts, files } = modelOutput;
-            if (text) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "text", content: text }] },
-                };
-            }
-            if (thoughts) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "thinking", thoughts }] },
-                };
+            if (text || thoughts) {
+                const content = [];
+                if (thoughts) {
+                    content.push({ type: "text", text: thoughts, isThinking: true });
+                }
+                if (text) {
+                    content.push({ type: "text", text });
+                }
+                if (content.length) {
+                    yield {
+                        progress: {
+                            event: "message",
+                            message: { role: "agent", content },
+                        },
+                    };
+                }
             }
             if (toolCalls?.length) {
                 if (this.keepTextInToolUses !== true) {
@@ -383,25 +392,14 @@ export class AIAgent extends Agent {
                         queue.killAndDrain();
                     }
                 }, this.toolCallsConcurrency || 1);
+                yield {
+                    progress: { event: "message", message: { role: "agent", toolCalls } },
+                };
                 // Execute tools
                 for (const call of toolCalls) {
                     const tool = toolsMap.get(call.function.name);
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
-                    yield {
-                        progress: {
-                            event: "message",
-                            role: "agent",
-                            message: [
-                                {
-                                    type: "tool_use",
-                                    name: call.function.name,
-                                    input: call.function.arguments,
-                                    toolUseId: call.id,
-                                },
-                            ],
-                        },
-                    };
                     queue.push({ tool, call });
                 }
                 await queue.drained();
@@ -413,14 +411,11 @@ export class AIAgent extends Agent {
                         yield {
                             progress: {
                                 event: "message",
-                                role: "agent",
-                                message: [
-                                    {
-                                        type: "tool_result",
-                                        toolUseId: call.id,
-                                        content: output,
-                                    },
-                                ],
+                                message: {
+                                    role: "tool",
+                                    toolCallId: call.id,
+                                    content: JSON.stringify(output),
+                                },
                             },
                         };
                     }
@@ -444,11 +439,6 @@ export class AIAgent extends Agent {
             if (!isEmpty(result)) {
                 yield { delta: { json: result } };
             }
-            if (text) {
-                yield {
-                    progress: { event: "message", role: "agent", message: [{ type: "text", content: text }] },
-                };
-            }
             return;
         }
     }

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

@@ -225,6 +225,7 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    isThinking?: boolean;
     /**
      * Cache control marker (only supported by Claude)
      *

package/lib/esm/loader/agent-yaml.d.ts

@@ -1,6 +1,6 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, TaskRenderMode } from "../agents/agent.js";
+import type { Agent, AgentHooks, TaskRenderMode } from "../agents/agent.js";
 import type { LoadOptions } from "./index.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -65,6 +65,7 @@ export interface AgentSchema {
         context?: AFSContextSchema;
     });
     shareAFS?: boolean;
+    historyConfig?: Agent["historyConfig"];
     [key: string]: unknown;
 }
 export declare function parseAgentFile(path: string, data: any, options: LoadOptions): Promise<AgentSchema>;

package/lib/esm/loader/agent-yaml.js

@@ -95,6 +95,14 @@ export const getAgentSchema = ({ filepath }) => {
                 })),
             ])),
             shareAFS: optionalize(z.boolean()),
+            historyConfig: camelizeSchema(optionalize(z.object({
+                enabled: optionalize(z.boolean()),
+                record: optionalize(z.boolean()),
+                inject: optionalize(z.boolean()),
+                use_old_memory: optionalize(z.boolean()),
+                maxTokens: optionalize(z.number().int().positive()),
+                maxItems: optionalize(z.number().int().positive()),
+            }))),
         });
         return camelizeSchema(baseAgentSchema.passthrough());
     });

package/lib/esm/prompt/context/afs/history.d.ts

@@ -1,5 +1,9 @@
+import type { AFSListOptions } from "@aigne/afs";
 import type { Agent } from "../../../agents/agent.js";
-export declare function getHistories(agent: Agent): Promise<{
+export declare function getHistories({ filter, agent, }: {
+    filter: AFSListOptions["filter"];
+    agent: Agent;
+}): Promise<{
     role: "user" | "agent";
     content: unknown;
 }[]>;

package/lib/esm/prompt/context/afs/history.js

@@ -1,6 +1,6 @@
 import { AFSHistory } from "@aigne/afs-history";
 import { isNonNullable } from "../../../utils/type-utils.js";
-export async function getHistories(agent) {
+export async function getHistories({ filter, agent, }) {
     const afs = agent?.afs;
     if (!afs)
         return [];
@@ -8,6 +8,7 @@ export async function getHistories(agent) {
     if (!historyModule)
         return [];
     const history = (await afs.list(historyModule.path, {
+        filter,
         limit: agent.historyConfig?.maxItems || 10,
         orderBy: [["createdAt", "desc"]],
     })).data;

package/lib/esm/prompt/context/afs/index.js

@@ -17,7 +17,14 @@ export function createAFSContext(agent, context) {
         get histories() {
             if (!agent)
                 return Promise.resolve([]);
-            return getHistories(agent);
+            return getHistories({
+                agent,
+                filter: {
+                    agentId: agent.name,
+                    userId: context?.userContext.userId,
+                    sessionId: context?.userContext.sessionId,
+                },
+            });
         },
         get skills() {
             const afs = agent?.afs;

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

@@ -1,14 +1,16 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
+import { Agent, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
-import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import { type ChatModel, type ChatModelInput, type ChatModelInputMessage } from "../agents/chat-model.js";
 import { type FileUnionContent } from "../agents/model.js";
+import type { Context } from "../aigne/context.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
 }
-export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
+export interface PromptBuildOptions {
+    context?: Context;
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;
@@ -37,10 +39,12 @@ export declare class PromptBuilder {
     }>;
     private getTemplateVariables;
     private buildMessages;
-    getHistories(options: PromptBuildOptions): Promise<{
-        role: "user" | "agent";
-        content: unknown;
-    }[]>;
+    protected deprecatedMemories(message: string | undefined, options: PromptBuildOptions): Promise<ChatModelInputMessage[]>;
+    getHistories({ agentId, userId, sessionId, ...options }: PromptBuildOptions & {
+        agentId?: string;
+        userId?: string;
+        sessionId?: string;
+    }): Promise<ChatModelInputMessage[]>;
     private refineMessages;
     private convertMemoriesToMessages;
     private buildResponseFormat;

package/lib/esm/prompt/prompt-builder.js

@@ -5,6 +5,7 @@ import { ZodObject } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { Agent } from "../agents/agent.js";
 import { DEFAULT_OUTPUT_FILE_KEY, DEFAULT_OUTPUT_KEY } from "../agents/ai-agent.js";
+import { roleSchema, } from "../agents/chat-model.js";
 import { fileUnionContentsSchema } from "../agents/model.js";
 import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
@@ -97,6 +98,9 @@ export class PromptBuilder {
     }
     async buildMessages(options) {
         const { input } = options;
+        const agentId = options.agent?.name;
+        const userId = options.context?.userContext.userId;
+        const sessionId = options.context?.userContext.sessionId;
         const inputKey = options.agent?.inputKey;
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
         const [messages, otherCustomMessages] = partition((await (typeof this.instructions === "string"
@@ -106,6 +110,50 @@ export class PromptBuilder {
         const files = flat(inputFileKey
             ? checkArguments("Check input files", optionalize(fileUnionContentsSchema), input?.[inputFileKey])
             : null);
+        const historyConfig = options.agent?.historyConfig;
+        const injectHistory = historyConfig?.inject === true || (historyConfig?.inject !== false && historyConfig?.enabled);
+        if (injectHistory) {
+            if (historyConfig.useOldMemory) {
+                messages.push(...(await this.deprecatedMemories(message, options)));
+            }
+            else {
+                const history = await this.getHistories({ ...options, agentId, userId, sessionId });
+                messages.push(...history);
+            }
+        }
+        // if the agent is using structured stream mode, add the instructions
+        const { structuredStreamMode, outputSchema } = options.agent || {};
+        if (structuredStreamMode && outputSchema) {
+            const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
+                PromptBuilder.from(STRUCTURED_STREAM_INSTRUCTIONS.instructions);
+            messages.push(...(await instructions.buildMessages({
+                input: {
+                    ...input,
+                    outputJsonSchema: zodToJsonSchema(outputSchema),
+                },
+            })));
+        }
+        messages.push(...otherCustomMessages);
+        if (message || files.length) {
+            const content = [];
+            if (message &&
+                // avoid duplicate user messages: developer may have already included the message in the messages
+                !otherCustomMessages.some((i) => i.role === "user" &&
+                    (typeof i.content === "string"
+                        ? i.content.includes(message)
+                        : i.content?.some((c) => c.type === "text" && c.text.includes(message))))) {
+                content.push({ type: "text", text: message });
+            }
+            if (files.length)
+                content.push(...files);
+            if (content.length) {
+                messages.push({ role: "user", content });
+            }
+        }
+        return this.refineMessages(options, messages);
+    }
+    async deprecatedMemories(message, options) {
+        const messages = [];
         const memories = [];
         if (options.agent && options.context) {
             memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
@@ -114,7 +162,7 @@ export class PromptBuilder {
             memories.push(...options.context.memories);
         }
         const afs = options.agent?.afs;
-        if (afs && options.agent?.historyConfig?.disabled !== true) {
+        if (afs && options.agent?.historyConfig?.enabled) {
             const historyModule = (await afs.listModules()).find((m) => m.module instanceof AFSHistory);
             if (historyModule) {
                 const history = await afs.list(historyModule.path, {
@@ -160,38 +208,9 @@ export class PromptBuilder {
         }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
-        // if the agent is using structured stream mode, add the instructions
-        const { structuredStreamMode, outputSchema } = options.agent || {};
-        if (structuredStreamMode && outputSchema) {
-            const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
-                PromptBuilder.from(STRUCTURED_STREAM_INSTRUCTIONS.instructions);
-            messages.push(...(await instructions.buildMessages({
-                input: {
-                    ...input,
-                    outputJsonSchema: zodToJsonSchema(outputSchema),
-                },
-            })));
-        }
-        if (message || files.length) {
-            const content = [];
-            if (message &&
-                // avoid duplicate user messages: developer may have already included the message in the custom user messages
-                !otherCustomMessages.some((i) => i.role === "user" &&
-                    (typeof i.content === "string"
-                        ? i.content.includes(message)
-                        : i.content?.some((c) => c.type === "text" && c.text.includes(message))))) {
-                content.push({ type: "text", text: message });
-            }
-            if (files.length)
-                content.push(...files);
-            if (content.length) {
-                messages.push({ role: "user", content });
-            }
-        }
-        messages.push(...otherCustomMessages);
-        return this.refineMessages(options, messages);
+        return messages;
     }
-    async getHistories(options) {
+    async getHistories({ agentId, userId, sessionId, ...options }) {
         const { agent } = options;
         const afs = agent?.afs;
         if (!afs)
@@ -200,24 +219,21 @@ export class PromptBuilder {
         if (!historyModule)
             return [];
         const history = (await afs.list(historyModule.path, {
+            filter: { agentId, userId, sessionId },
             limit: agent.historyConfig?.maxItems || 10,
             orderBy: [["createdAt", "desc"]],
-        })).data;
-        return history
-            .reverse()
-            .map((i) => {
-            if (!i.content)
-                return;
-            const { input, output } = i.content;
-            if (!input || !output)
-                return;
-            return [
-                { role: "user", content: input },
-                { role: "agent", content: output },
-            ];
-        })
-            .filter(isNonNullable)
-            .flat();
+        })).data.reverse();
+        return (await Promise.all(history.map(async (i) => {
+            if (Array.isArray(i.content?.messages) &&
+                i.content.messages.every((m) => roleSchema.parse(m?.role))) {
+                return i.content.messages;
+            }
+            const { input, output } = i.content || {};
+            if (input && output) {
+                return await this.convertMemoriesToMessages([{ content: { input, output } }], options);
+            }
+            return [];
+        }))).flat();
     }
     refineMessages(options, messages) {
         const { autoReorderSystemMessages, autoMergeSystemMessages } = options.agent ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.72.0-beta.6",
+  "version": "1.72.0-beta.7",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -93,10 +93,10 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/afs": "^1.4.0-beta.3",
-    "@aigne/afs-history": "^1.2.0-beta.3",
-    "@aigne/platform-helpers": "^0.6.7-beta",
-    "@aigne/observability-api": "^0.11.14-beta.1"
+    "@aigne/afs": "^1.4.0-beta.4",
+    "@aigne/afs-history": "^1.2.0-beta.4",
+    "@aigne/observability-api": "^0.11.14-beta.1",
+    "@aigne/platform-helpers": "^0.6.7-beta"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",