@aigne/core 1.72.0-beta.2 → 1.72.0-beta.23

package/lib/cjs/prompt/skills/afs/write.js

@@ -7,16 +7,30 @@ class AFSWriteAgent extends base_js_1.AFSSkillBase {
     constructor(options) {
         super({
             name: "afs_write",
-            description: "Create new file or append content to existing file. Use when creating files, rewriting entire files, or appending to files.",
+            description: `Write or create files in the Agentic File System (AFS)
+- Creates a new file or overwrites an existing file with the provided content
+- Supports append mode to add content to the end of existing files
+- Use this tool when creating new files or completely replacing file contents
+
+Usage:
+- The path must be an absolute AFS path starting with "/" (e.g., "/docs/new-file.md", "/memory/user/notes")
+- This is NOT a local system file path - it operates within the AFS virtual file system
+- By default, this tool overwrites the entire file content
+- Use append mode to add content to the end of an existing file without replacing it
+- For partial edits to existing files, prefer using afs_edit instead`,
             ...options,
             inputSchema: zod_1.z.object({
-                path: zod_1.z.string().describe("Absolute file path to write"),
-                content: zod_1.z.string().describe("Complete file content or content to append"),
+                path: zod_1.z
+                    .string()
+                    .describe("Absolute AFS path for the file to write (e.g., '/docs/new-file.md'). Must start with '/'"),
+                content: zod_1.z
+                    .string()
+                    .describe("The content to write to the file. In overwrite mode, this replaces the entire file"),
                 append: zod_1.z
                     .boolean()
                     .optional()
                     .default(false)
-                    .describe("Append mode: add content to end of file (default: false, overwrites file)"),
+                    .describe("Set to true to append content to the end of an existing file. Default: false (overwrites entire file)"),
             }),
             outputSchema: zod_1.z.object({
                 status: zod_1.z.string(),
@@ -29,7 +43,7 @@ class AFSWriteAgent extends base_js_1.AFSSkillBase {
     async process(input, _options) {
         if (!this.afs)
             throw new Error("AFS is not configured for this agent.");
-        const result = await this.afs.write(input.path, {
+        const _result = await this.afs.write(input.path, {
             content: input.content,
         }, {
             append: input.append ?? false,
@@ -38,7 +52,7 @@ class AFSWriteAgent extends base_js_1.AFSSkillBase {
             status: "success",
             tool: "afs_write",
             path: input.path,
-            ...result,
+            message: "File written successfully",
         };
     }
 }

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

@@ -27,35 +27,38 @@ export declare class ChatMessageTemplate {
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     options?: FormatOptions | undefined;
-    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
+    cacheControl?: ChatModelInputMessage["cacheControl"];
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): UserMessageTemplate;
 }
 export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
-    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
-    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "agent" | "user" | "system" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCalls: ChatModelOutputToolCall[] | undefined;
+        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
     }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
-    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
-    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "agent" | "user" | "system" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCallId: string;
+        cacheControl: import("../agents/chat-model.js").CacheControl | undefined;
     }>;
 }
 export declare class ChatMessagesTemplate {
@@ -69,26 +72,62 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: z.ZodLiteral<"system">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"user">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"agent">;
     content: z.ZodOptional<z.ZodString>;
@@ -121,10 +160,24 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         id: string;
     }>, "many">>;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "agent";
     name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -137,6 +190,10 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: "agent";
     name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -150,16 +207,34 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
     toolCallId: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "tool";
     content: string;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "tool";
     content: string | Record<string, unknown>;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>]>;
 export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
 export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {

package/lib/cjs/prompt/template.js

@@ -80,11 +80,13 @@ class ChatMessageTemplate {
     content;
     name;
     options;
-    constructor(role, content, name, options) {
+    cacheControl;
+    constructor(role, content, name, options, cacheControl) {
         this.role = role;
         this.content = content;
         this.name = name;
         this.options = options;
+        this.cacheControl = cacheControl;
     }
     async format(variables, options) {
         options = { ...this.options, ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)) };
@@ -103,29 +105,30 @@ class ChatMessageTemplate {
             role: this.role,
             content,
             name: this.name,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.ChatMessageTemplate = ChatMessageTemplate;
 class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content, name, options) {
-        return new SystemMessageTemplate("system", content, name, options);
+    static from(content, name, options, cacheControl) {
+        return new SystemMessageTemplate("system", content, name, options, cacheControl);
     }
 }
 exports.SystemMessageTemplate = SystemMessageTemplate;
 class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template, name, options) {
-        return new UserMessageTemplate("user", template, name, options);
+    static from(template, name, options, cacheControl) {
+        return new UserMessageTemplate("user", template, name, options, cacheControl);
     }
 }
 exports.UserMessageTemplate = UserMessageTemplate;
 class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls;
-    static from(template, toolCalls, name, options) {
-        return new AgentMessageTemplate(template, toolCalls, name, options);
+    static from(template, toolCalls, name, options, cacheControl) {
+        return new AgentMessageTemplate(template, toolCalls, name, options, cacheControl);
     }
-    constructor(content, toolCalls, name, options) {
-        super("agent", content, name, options);
+    constructor(content, toolCalls, name, options, cacheControl) {
+        super("agent", content, name, options, cacheControl);
         this.toolCalls = toolCalls;
     }
     async format(_variables, _options) {
@@ -135,17 +138,18 @@ class AgentMessageTemplate extends ChatMessageTemplate {
             // NOTE: agent message should not rendered by template
             content: this.content,
             toolCalls: this.toolCalls,
+            cacheControl: this.cacheControl,
         };
     }
 }
 exports.AgentMessageTemplate = AgentMessageTemplate;
 class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId;
-    static from(content, toolCallId, name, options) {
-        return new ToolMessageTemplate(content, toolCallId, name, options);
+    static from(content, toolCallId, name, options, cacheControl) {
+        return new ToolMessageTemplate(content, toolCallId, name, options, cacheControl);
     }
-    constructor(content, toolCallId, name, options) {
-        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options);
+    constructor(content, toolCallId, name, options, cacheControl) {
+        super("tool", typeof content === "string" ? content : (0, yaml_1.stringify)(content), name, options, cacheControl);
         this.toolCallId = toolCallId;
     }
     async format(_variables, _options) {
@@ -155,6 +159,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
             // NOTE: tool result should not rendered by template
             content: this.content,
             toolCallId: this.toolCallId,
+            cacheControl: this.cacheControl,
         };
     }
 }
@@ -179,11 +184,23 @@ const systemChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("system"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const userChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("user"),
     content: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatModelOutputToolCallSchema = zod_1.z.object({
     id: zod_1.z.string(),
@@ -198,6 +215,12 @@ const agentChatMessageSchema = zod_1.z.object({
     content: zod_1.z.string().optional(),
     toolCalls: zod_1.z.array(chatModelOutputToolCallSchema).optional(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const toolChatMessageSchema = zod_1.z.object({
     role: zod_1.z.literal("tool"),
@@ -206,6 +229,12 @@ const toolChatMessageSchema = zod_1.z.object({
         .transform((val) => (typeof val !== "string" ? JSON.stringify(val) : val)),
     toolCallId: zod_1.z.string(),
     name: zod_1.z.string().optional(),
+    cacheControl: zod_1.z
+        .object({
+        type: zod_1.z.literal("ephemeral"),
+        ttl: zod_1.z.union([zod_1.z.literal("5m"), zod_1.z.literal("1h")]).optional(),
+    })
+        .optional(),
 });
 const chatMessageSchema = zod_1.z.union([
     systemChatMessageSchema,
@@ -224,13 +253,13 @@ function parseChatMessages(messages) {
     return messages.map((message) => {
         switch (message.role) {
             case "system":
-                return SystemMessageTemplate.from(message.content, message.name, message.options);
+                return SystemMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "user":
-                return UserMessageTemplate.from(message.content, message.name, message.options);
+                return UserMessageTemplate.from(message.content, message.name, message.options, message.cacheControl);
             case "agent":
-                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options);
+                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options, message.cacheControl);
             case "tool":
-                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options);
+                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options, message.cacheControl);
         }
     });
 }

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

@@ -48,5 +48,5 @@ function resourceFromMCPResource(resource, options) {
     });
 }
 function isResourceTemplate(resource) {
-    return typeof resource.uriTemplate === "string";
+    return "uriTemplate" in resource && typeof resource.uriTemplate === "string";
 }

package/lib/cjs/utils/token-estimator.js

@@ -8,7 +8,7 @@ exports.estimateTokens = estimateTokens;
 const CHAR_TYPE_RATIOS = {
     chinese: 1.5, // Chinese characters: ~1.5 characters per token
     word: 0.75, // English words: ~0.75 tokens per word (accounting for subword tokenization)
-    other: 4, // Other characters (punctuation, numbers, etc.): ~4 characters per token
+    other: 1, // Other characters (punctuation, numbers, etc.): ~1 character per token
 };
 /**
  * Regular expressions for character type detection

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

@@ -1,7 +1,7 @@
 import { AFS, type AFSExecOptions, type AFSExecResult, type AFSListOptions, type AFSListResult, type AFSModule, type AFSOptions, type AFSReadResult, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
-import { type ZodObject, type ZodType } from "zod";
+import { type ZodObject, type ZodType, z } from "zod";
 import type { AgentEvent, Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
 import type { ContextUsage } from "../aigne/usage.js";
@@ -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";
@@ -118,7 +118,6 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * agentSucceed, or agentFailed
      */
     disableEvents?: boolean;
-    historyConfig?: Agent["historyConfig"];
     /**
      * One or more memory agents this agent can use
      */
@@ -173,6 +172,10 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * This property only exists in the CLI context by command `aigne run`
      */
     prompts?: typeof prompts;
+    /**
+     * The caller agent that invoked this agent
+     */
+    caller?: Agent;
 }
 /**
  * Agent is the base class for all agents.
@@ -211,15 +214,15 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
         parsed: object;
     }): Promise<Agent<I, O>>;
     constructor(options?: AgentOptions<I, O>);
+    afs?: AFS;
+    tag?: string;
     /**
      * List of memories this agent can use
      *
      * @deprecated use afs instead
      */
     readonly memories: MemoryAgent[];
-    afs?: AFS;
     asyncMemoryRecord?: boolean;
-    tag?: string;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -349,11 +352,6 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * agentSucceed, or agentFailed
      */
     private disableEvents?;
-    historyConfig?: {
-        disabled?: boolean;
-        maxTokens?: number;
-        maxItems?: number;
-    };
     private subscriptions;
     /**
      * Attach agent to context:
@@ -455,7 +453,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
      *
@@ -517,6 +517,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     protected postprocess(input: I, output: O, options: AgentInvokeOptions): Promise<void>;
     protected publishToTopics(output: Message, options: AgentInvokeOptions): Promise<void>;
+    formatOutput(output: O): PromiseOrValue<string>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
      *
@@ -783,12 +784,31 @@ export interface AgentResponseProgress {
     } | {
         event: "agentFailed";
         error: Error;
+    } | {
+        event: "message";
+        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
@@ -870,6 +890,17 @@ export interface FunctionAgentOptions<I extends Message = Message, O extends Mes
  */
 export declare class FunctionAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     tag: string;
+    static schema(): ZodObject<{
+        process: ZodType<FunctionAgentFn>;
+    }, "strip", z.ZodTypeAny, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     /**
      * Create a function agent from a function or options
      *

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

@@ -1,4 +1,8 @@
 import { type ZodObject, type ZodType, z } from "zod";
+import { type NestAgentSchema } from "../loader/agent-yaml.js";
+import type { AgentLoadOptions } from "../loader/index.js";
+import { type Instructions } from "../loader/schema.js";
+import type { CompactConfig, SessionMemoryConfig, UserMemoryConfig } from "../prompt/agent-session.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
 import type { ChatModel, ChatModelInput } from "./chat-model.js";
@@ -23,8 +27,6 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * more complex prompt templates
      */
     instructions?: string | PromptBuilder;
-    autoReorderSystemMessages?: boolean;
-    autoMergeSystemMessages?: boolean;
     /**
      * Pick a message from input to use as the user's message
      */
@@ -124,6 +126,53 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      */
     memoryPromptTemplate?: string;
     useMemoriesFromContext?: boolean;
+    /**
+     * Agent session configuration
+     *
+     * Controls history recording, memory extraction, and conversation compaction.
+     * By default, mode is "auto" (enabled). Set `{ mode: "disabled" }` to disable
+     * for internal utility agents (extractors, compactors, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Default behavior - session features enabled
+     * new AIAgent({
+     *   session: {
+     *     compact: { mode: "auto" },
+     *     sessionMemory: { mode: "auto" },
+     *     userMemory: { mode: "auto" }
+     *   }
+     * })
+     *
+     * // Disable for internal utility agents
+     * new AIAgent({
+     *   session: { mode: "disabled" }
+     * })
+     * ```
+     */
+    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
+}
+export interface AIAgentLoadSchema {
+    instructions?: Instructions;
+    inputKey?: string;
+    inputFileKey?: string;
+    outputKey?: string;
+    outputFileKey?: string;
+    toolChoice?: AIAgentToolChoice;
+    toolCallsConcurrency?: number;
+    keepTextInToolUses?: boolean;
+    session?: {
+        mode?: "auto" | "disabled";
+        compact?: Omit<CompactConfig, "compactor"> & {
+            compactor?: NestAgentSchema;
+        };
+        sessionMemory?: Omit<SessionMemoryConfig, "extractor"> & {
+            extractor?: NestAgentSchema;
+        };
+        userMemory?: Omit<UserMemoryConfig, "extractor"> & {
+            extractor?: NestAgentSchema;
+        };
+    };
 }
 /**
  * Tool choice options for AI agents
@@ -188,6 +237,14 @@ export declare const aiAgentOptionsSchema: ZodObject<{
  */
 export declare class AIAgent<I extends Message = any, O extends Message = any> extends Agent<I, O> {
     tag: string;
+    static schema<T>({ filepath }: {
+        filepath: string;
+    }): ZodType<T>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+        options?: AgentLoadOptions;
+    }): Promise<Agent<I, O>>;
     /**
      * Create an AIAgent with the specified options
      *
@@ -218,8 +275,6 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
      */
     instructions: PromptBuilder;
-    autoReorderSystemMessages?: boolean;
-    autoMergeSystemMessages?: boolean;
     /**
      * Pick a message from input to use as the user's message
      */
@@ -315,6 +370,10 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
         metadataEnd: string;
         parse: (raw: string) => object;
     };
+    /**
+     * Agent session configuration
+     */
+    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
     get inputSchema(): ZodType<I>;
     /**
      * Process an input message and generate a response