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

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

@@ -5,9 +5,8 @@ import type { ChatModel } from "../agents/chat-model.js";
 import type { ImageModel } from "../agents/image-model.js";
 import type { AIGNEOptions } from "../aigne/aigne.js";
 import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
-import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
-import { type Instructions, loadAgentFromYamlFile, type NestAgentSchema } from "./agent-yaml.js";
+import { loadAgentFromYamlFile, type NestAgentSchema } from "./agent-yaml.js";
 export interface LoadOptions {
     memories?: {
         new (parameters?: MemoryAgentOptions): MemoryAgent;
@@ -19,7 +18,10 @@ export interface LoadOptions {
         availableModules?: {
             module: string;
             alias?: string[];
-            create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
+            load: (options: {
+                filepath: string;
+                parsed?: object;
+            }) => PromiseOrValue<AFSModule>;
         }[];
     };
     aigne?: z.infer<typeof aigneFileSchema>;
@@ -27,6 +29,9 @@ export interface LoadOptions {
         parent?: string;
     }) => Promise<any>;
 }
+export interface AgentLoadOptions extends LoadOptions {
+    loadNestAgent: (path: string, agent: NestAgentSchema, options: LoadOptions, agentOptions?: AgentOptions<any, any> & Record<string, unknown>) => Promise<Agent>;
+}
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 export declare function loadNestAgent(path: string, agent: NestAgentSchema, options: LoadOptions, agentOptions?: AgentOptions<any, any> & Record<string, unknown>): Promise<Agent>;
@@ -67,9 +72,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined, z.ZodTypeDef, z.objectInputType<{
@@ -98,9 +103,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined>;
@@ -158,9 +163,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -209,9 +214,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -239,5 +244,4 @@ export declare function loadAIGNEFile(path: string): Promise<{
     rootDir: string;
 }>;
 export declare function findAIGNEFile(path: string): Promise<string>;
-export declare function instructionsToPromptBuilder(instructions: Instructions): PromptBuilder;
 export {};

package/lib/dts/loader/schema.d.ts

@@ -1,4 +1,6 @@
 import { type ZodType, z } from "zod";
+import { type Role } from "../agents/chat-model.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
 export declare const inputOutputSchema: ({ path }: {
     path: string;
 }) => z.ZodUnion<[ZodType<any, z.ZodTypeDef, any>, z.ZodEffects<z.ZodObject<{
@@ -55,9 +57,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -86,9 +88,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -117,9 +119,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">>;
@@ -149,4 +151,17 @@ export declare function camelizeSchema<T extends ZodType>(schema: T, { shallow }
     shallow?: boolean;
 }): T;
 export declare function preprocessSchema<T extends ZodType>(fn: (data: unknown) => unknown, schema: T): T;
+export type Instructions = {
+    role: Exclude<Role, "tool">;
+    content: string;
+    path: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
+}[];
+export declare const getInstructionsSchema: ({ filepath }: {
+    filepath: string;
+}) => ZodType<Instructions>;
+export declare function instructionsToPromptBuilder(instructions: Instructions | string): PromptBuilder;
 export {};

package/lib/dts/memory/recorder.d.ts

@@ -42,24 +42,24 @@ export declare const memoryRecorderOutputSchema: z.ZodObject<{
         content: ZodType<{}, z.ZodTypeDef, {}>;
         createdAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }>;

package/lib/dts/memory/retriever.d.ts

@@ -55,24 +55,24 @@ export declare const memoryRetrieverOutputSchema: z.ZodObject<{
         content: z.ZodType<{}, z.ZodTypeDef, {}>;
         createdAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }>;

package/lib/dts/prompt/agent-session.d.ts

@@ -0,0 +1,163 @@
+import type { AFS } from "@aigne/afs";
+import type { AgentInvokeOptions } from "../agents/agent.js";
+import type { ChatModelInputMessage } from "../agents/chat-model.js";
+import { type CompactConfig, type SessionMemoryConfig, type SessionMode, type UserMemoryConfig } from "./compact/types.js";
+export * from "./compact/types.js";
+export interface AgentSessionOptions {
+    sessionId: string;
+    userId?: string;
+    agentId?: string;
+    afs?: AFS;
+    /**
+     * Session mode
+     * - "auto": Enable history recording, compaction, and memory extraction
+     * - "disabled": Disable all session features (history, compaction, memory)
+     *
+     * **Should be "disabled" for internal utility agents** (extractors, compactors, etc.)
+     * to avoid recursive memory extraction and unnecessary overhead.
+     *
+     * @default DEFAULT_SESSION_MODE ("auto")
+     */
+    mode?: SessionMode;
+    /**
+     * Compaction configuration
+     */
+    compact?: CompactConfig;
+    /**
+     * Session memory configuration
+     */
+    sessionMemory?: SessionMemoryConfig;
+    /**
+     * User memory configuration
+     */
+    userMemory?: UserMemoryConfig;
+}
+export declare class AgentSession {
+    readonly sessionId: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+    private afs?;
+    private historyModulePath?;
+    private mode;
+    private compactConfig;
+    private sessionMemoryConfig;
+    private userMemoryConfig;
+    private runtimeState;
+    private initialized?;
+    private compactionPromise?;
+    private sessionMemoryUpdatePromise?;
+    private userMemoryUpdatePromise?;
+    constructor(options: AgentSessionOptions);
+    /**
+     * Check if memory extraction is enabled
+     * Memory extraction requires mode to be "auto" AND AFS history module to be available
+     */
+    private get isMemoryEnabled();
+    setSystemMessages(...messages: ChatModelInputMessage[]): Promise<void>;
+    getMessages(): Promise<ChatModelInputMessage[]>;
+    /**
+     * Format user memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatUserMemory;
+    /**
+     * Format session memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatSessionMemory;
+    private formatMemoryTemplate;
+    startMessage(input: unknown, message: ChatModelInputMessage, options: AgentInvokeOptions): Promise<void>;
+    endMessage(output: unknown, message: ChatModelInputMessage | undefined, options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Manually trigger compaction
+     */
+    compact(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual compaction
+     */
+    private doCompact;
+    private compactCurrentEntry;
+    private maybeCompactCurrentEntry;
+    private maybeAutoCompact;
+    /**
+     * Estimate token count for messages
+     * Applies singleMessageLimit to each text block individually
+     * Non-text tokens (images, tool calls) are always counted in full
+     */
+    private estimateMessagesTokens;
+    /**
+     * Split entries into batches based on token limit
+     * Each batch will not exceed the specified maxTokens
+     */
+    private splitIntoBatches;
+    appendCurrentMessages(messages: ChatModelInputMessage | ChatModelInputMessage[], options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Truncate text content to fit within target token limit
+     * @param text The text to truncate
+     * @param currentTokens Current token count of the text
+     * @param targetTokens Target token count after truncation
+     * @returns Truncated text
+     */
+    private truncateText;
+    private truncateLargeMessage;
+    private ensureInitialized;
+    private initialize;
+    /**
+     * Load session memory facts
+     * @returns Array of memory fact entries for the current session
+     */
+    private loadSessionMemory;
+    /**
+     * Load user memory facts
+     * @returns Array of memory fact entries for the current user
+     */
+    private loadUserMemory;
+    /**
+     * Load session history including compact content and history entries
+     * @returns Object containing history compact and history entries
+     */
+    private loadSessionHistory;
+    /**
+     * Manually trigger session memory update
+     */
+    updateSessionMemory(options: AgentInvokeOptions): Promise<void>;
+    private maybeAutoUpdateSessionMemory;
+    private maybeAutoUpdateUserMemory;
+    /**
+     * Internal method that performs the actual session memory update
+     */
+    private doUpdateSessionMemory;
+    /**
+     * Manually trigger user memory update
+     */
+    updateUserMemory(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual user memory extraction
+     */
+    private doUpdateUserMemory;
+    /**
+     * Find Agent Skill content from a single message
+     * @param msg - Message to search in
+     * @returns The skill content text if found, undefined otherwise
+     */
+    private findSkillContentInMessage;
+    /**
+     * Find the last Agent Skill from a list of messages
+     * @param messages - Messages to search through
+     * @returns The last Agent Skill found, or undefined if none found
+     */
+    private findLastAgentSkillFromMessages;
+    /**
+     * Find the last Agent Skill from a list of history entries
+     * @param entries - History entries to search through
+     * @returns The last Agent Skill found, or undefined if none found
+     */
+    private findLastAgentSkill;
+    private initializeDefaultCompactor;
+    private initializeDefaultSessionMemoryExtractor;
+    private initializeDefaultUserMemoryExtractor;
+    private get maxTokens();
+    private get keepRecentRatio();
+    private get keepRecentTokens();
+    private get singleMessageLimit();
+}

package/lib/dts/prompt/compact/compactor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { CompactContent, CompactorInput } from "./types.js";
+export interface CreateCompactorOptions extends AIAgentOptions<CompactorInput, CompactContent> {
+}
+export declare class AISessionCompactor extends AIAgent<CompactorInput, CompactContent> {
+    constructor(options?: CreateCompactorOptions);
+}

package/lib/dts/prompt/compact/session-memory-extractor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { MemoryExtractorInput, MemoryExtractorOutput } from "./types.js";
+export interface CreateSessionMemoryExtractorOptions extends AIAgentOptions<MemoryExtractorInput, MemoryExtractorOutput> {
+}
+export declare class AISessionMemoryExtractor extends AIAgent<MemoryExtractorInput, MemoryExtractorOutput> {
+    constructor(options?: CreateSessionMemoryExtractorOptions);
+}