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

package/lib/esm/prompt/agent-session.js

@@ -0,0 +1,304 @@
+import { AFSHistory } from "@aigne/afs-history";
+import { v7 } from "@aigne/uuid";
+import { joinURL } from "ufo";
+import { estimateTokens } from "../utils/token-estimator.js";
+import { isNonNullable } from "../utils/type-utils.js";
+import { DEFAULT_COMPACT_ASYNC, DEFAULT_COMPACT_MODE, DEFAULT_KEEP_RECENT_RATIO, DEFAULT_MAX_TOKENS, } from "./compact/types.js";
+export class AgentSession {
+    sessionId;
+    userId;
+    agentId;
+    afs;
+    historyModulePath;
+    compactConfig;
+    runtimeState;
+    initialized;
+    compactionPromise;
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this.userId = options.userId;
+        this.agentId = options.agentId;
+        this.afs = options.afs;
+        this.compactConfig = options.compact ?? {};
+        this.runtimeState = {
+            historyEntries: [],
+            currentEntry: null,
+        };
+    }
+    async setSystemMessages(...messages) {
+        await this.ensureInitialized();
+        this.runtimeState.systemMessages = messages;
+    }
+    async getMessages() {
+        await this.ensureInitialized();
+        const { systemMessages, compactSummary, historyEntries, currentEntry } = this.runtimeState;
+        const messages = [
+            ...(systemMessages ?? []),
+            ...(compactSummary
+                ? [
+                    {
+                        role: "system",
+                        content: `Previous conversation summary:\n${compactSummary}`,
+                    },
+                ]
+                : []),
+            ...historyEntries.flatMap((entry) => entry.content?.messages ?? []),
+            ...(currentEntry?.messages ?? []),
+        ];
+        // Filter out thinking messages from content
+        return messages.map((msg) => {
+            if (!msg.content || typeof msg.content === "string") {
+                return msg;
+            }
+            // Filter out thinking from UnionContent[]
+            const filteredContent = msg.content.filter((c) => !(c.type === "text" && c.isThinking));
+            return { ...msg, content: filteredContent.length > 0 ? filteredContent : undefined };
+        });
+    }
+    async startMessage(input, message, options) {
+        await this.ensureInitialized();
+        await this.maybeAutoCompact(options);
+        // Always wait for compaction to complete before starting a new message
+        // This ensures data consistency even in async compact mode
+        if (this.compactionPromise)
+            await this.compactionPromise;
+        this.runtimeState.currentEntry = { input, messages: [message] };
+    }
+    async endMessage(output, options) {
+        await this.ensureInitialized();
+        if (!this.runtimeState.currentEntry?.input ||
+            !this.runtimeState.currentEntry.messages?.length) {
+            throw new Error("No current entry to end. Call startMessage() first.");
+        }
+        this.runtimeState.currentEntry.output = output;
+        let newEntry;
+        if (this.afs && this.historyModulePath) {
+            newEntry = (await this.afs.write(joinURL(this.historyModulePath, "new"), {
+                userId: this.userId,
+                sessionId: this.sessionId,
+                agentId: this.agentId,
+                content: this.runtimeState.currentEntry,
+            })).data;
+        }
+        else {
+            const id = v7();
+            newEntry = {
+                id,
+                path: `/history/${id}`,
+                userId: this.userId,
+                sessionId: this.sessionId,
+                agentId: this.agentId,
+                content: this.runtimeState.currentEntry,
+            };
+        }
+        this.runtimeState.historyEntries.push(newEntry);
+        this.runtimeState.currentEntry = null;
+        // Check if auto-compact should be triggered
+        await this.maybeAutoCompact(options);
+    }
+    /**
+     * Manually trigger compaction
+     */
+    async compact(options) {
+        await this.ensureInitialized();
+        // If compaction is already in progress, wait for it to complete
+        if (this.compactionPromise) {
+            return this.compactionPromise;
+        }
+        // Start new compaction task
+        this.compactionPromise = this.doCompact(options).finally(() => {
+            this.compactionPromise = undefined;
+        });
+        return this.compactionPromise;
+    }
+    /**
+     * Internal method that performs the actual compaction
+     */
+    async doCompact(options) {
+        const { compactor, keepRecentRatio } = this.compactConfig ?? {};
+        if (!compactor) {
+            throw new Error("Cannot compact without a compactor agent configured.");
+        }
+        const historyEntries = this.runtimeState.historyEntries;
+        if (historyEntries.length === 0)
+            return;
+        // Calculate token budget for keeping recent messages
+        const ratio = keepRecentRatio ?? DEFAULT_KEEP_RECENT_RATIO;
+        const maxTokens = this.compactConfig?.maxTokens ?? DEFAULT_MAX_TOKENS;
+        let keepTokenBudget = Math.floor(maxTokens * ratio);
+        // Calculate tokens for system messages
+        const systemTokens = (this.runtimeState.systemMessages ?? []).reduce((sum, msg) => {
+            const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
+            return sum + estimateTokens(content);
+        }, 0);
+        // Calculate tokens for current entry messages
+        const currentTokens = (this.runtimeState.currentEntry?.messages ?? []).reduce((sum, msg) => {
+            const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
+            return sum + estimateTokens(content);
+        }, 0);
+        // Subtract system and current tokens from budget
+        // This ensures total tokens (system + current + kept history) stays within ratio budget
+        keepTokenBudget = Math.max(0, keepTokenBudget - systemTokens - currentTokens);
+        // Find split point by iterating backwards from most recent entry
+        // The split point divides history into: [compact] | [keep]
+        let splitIndex = historyEntries.length; // Default: keep all (no compaction)
+        let accumulatedTokens = 0;
+        for (let i = historyEntries.length - 1; i >= 0; i--) {
+            const entry = historyEntries[i];
+            if (!entry)
+                continue;
+            const entryTokens = this.estimateMessagesTokens(entry.content?.messages ?? []);
+            // Check if adding this entry would exceed token budget
+            if (accumulatedTokens + entryTokens > keepTokenBudget) {
+                // Would exceed budget, split here (this entry and earlier ones will be compacted)
+                splitIndex = i + 1;
+                break;
+            }
+            // Can keep this entry, accumulate and continue
+            accumulatedTokens += entryTokens;
+            splitIndex = i;
+        }
+        // Split history at the found point
+        const entriesToCompact = historyEntries.slice(0, splitIndex);
+        const entriesToKeep = historyEntries.slice(splitIndex);
+        // If nothing to compact, return
+        if (entriesToCompact.length === 0) {
+            return;
+        }
+        const latestCompactedEntry = entriesToCompact.at(-1);
+        if (!latestCompactedEntry)
+            return;
+        // Split into batches to avoid context overflow
+        const batches = this.splitIntoBatches(entriesToCompact, maxTokens);
+        // Process batches incrementally, each summary becomes input for the next
+        let currentSummary = this.runtimeState.compactSummary;
+        for (const batch of batches) {
+            const result = await options.context.invoke(compactor, {
+                previousSummary: [currentSummary].filter(isNonNullable),
+                messages: batch.flatMap((e) => e.content?.messages ?? []).filter(isNonNullable),
+            });
+            currentSummary = result.summary;
+        }
+        // Write compact entry to AFS
+        if (this.afs && this.historyModulePath) {
+            await this.afs.write(joinURL(this.historyModulePath, "by-session", this.sessionId, "@metadata/compact/new"), {
+                userId: this.userId,
+                agentId: this.agentId,
+                content: { summary: currentSummary },
+                metadata: {
+                    latestEntryId: latestCompactedEntry.id,
+                },
+            });
+        }
+        // Update runtime state: keep the summary and recent entries
+        this.runtimeState.compactSummary = currentSummary;
+        this.runtimeState.historyEntries = entriesToKeep;
+    }
+    async maybeAutoCompact(options) {
+        if (this.compactionPromise)
+            await this.compactionPromise;
+        if (!this.compactConfig)
+            return;
+        // Check if compaction is disabled
+        const mode = this.compactConfig.mode ?? DEFAULT_COMPACT_MODE;
+        if (mode === "disabled")
+            return;
+        const { compactor } = this.compactConfig;
+        const maxTokens = this.compactConfig.maxTokens ?? DEFAULT_MAX_TOKENS;
+        if (!compactor)
+            return;
+        const currentTokens = this.estimateMessagesTokens(await this.getMessages());
+        if (currentTokens >= maxTokens) {
+            this.compact(options);
+            const isAsync = this.compactConfig.async ?? DEFAULT_COMPACT_ASYNC;
+            if (!isAsync)
+                await this.compactionPromise;
+        }
+    }
+    /**
+     * Estimate token count for an array of messages
+     */
+    estimateMessagesTokens(messages) {
+        return messages.reduce((sum, msg) => {
+            const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
+            return sum + estimateTokens(content);
+        }, 0);
+    }
+    /**
+     * Split entries into batches based on token limit
+     * Each batch will not exceed the specified maxTokens
+     */
+    splitIntoBatches(entries, maxTokens) {
+        const batches = [];
+        let currentBatch = [];
+        let currentTokens = 0;
+        for (const entry of entries) {
+            const entryTokens = this.estimateMessagesTokens(entry.content?.messages ?? []);
+            // If adding this entry exceeds limit and we have entries in current batch, start new batch
+            if (currentTokens + entryTokens > maxTokens && currentBatch.length > 0) {
+                batches.push(currentBatch);
+                currentBatch = [entry];
+                currentTokens = entryTokens;
+            }
+            else {
+                currentBatch.push(entry);
+                currentTokens += entryTokens;
+            }
+        }
+        // Add remaining entries
+        if (currentBatch.length > 0) {
+            batches.push(currentBatch);
+        }
+        return batches;
+    }
+    async appendCurrentMessages(...messages) {
+        await this.ensureInitialized();
+        if (!this.runtimeState.currentEntry || !this.runtimeState.currentEntry.messages?.length) {
+            throw new Error("No current entry to append messages. Call startMessage() first.");
+        }
+        this.runtimeState.currentEntry.messages.push(...messages);
+    }
+    async ensureInitialized() {
+        this.initialized ??= this.initialize();
+        await this.initialized;
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.initializeDefaultCompactor();
+        const historyModule = (await this.afs?.listModules())?.find((m) => m.module instanceof AFSHistory);
+        this.historyModulePath = historyModule?.path;
+        if (this.afs && this.historyModulePath) {
+            // Load latest compact entry if exists
+            const compactPath = joinURL(this.historyModulePath, "by-session", this.sessionId, "@metadata/compact");
+            const compactResult = await this.afs.list(compactPath, {
+                filter: { userId: this.userId, agentId: this.agentId },
+                orderBy: [["createdAt", "desc"]],
+                limit: 1,
+            });
+            const latestCompact = compactResult.data[0];
+            if (latestCompact?.content?.summary) {
+                this.runtimeState.compactSummary = latestCompact.content.summary;
+            }
+            // Load history entries (after compact point if exists)
+            const afsEntries = (await this.afs.list(joinURL(this.historyModulePath, "by-session", this.sessionId), {
+                filter: {
+                    userId: this.userId,
+                    agentId: this.agentId,
+                    // Only load entries after the latest compact
+                    after: latestCompact?.createdAt?.toISOString(),
+                },
+                orderBy: [["createdAt", "desc"]],
+                // Set a very large limit to load all history entries
+                // The default limit is 10 which would cause history truncation
+                limit: 10000,
+            })).data;
+            this.runtimeState.historyEntries = afsEntries
+                .reverse()
+                .filter((entry) => isNonNullable(entry.content));
+        }
+    }
+    async initializeDefaultCompactor() {
+        this.compactConfig.compactor ??= await import("./compact/compactor.js").then((m) => new m.AISessionCompactor());
+    }
+}

package/lib/esm/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/esm/prompt/compact/compactor.js

@@ -0,0 +1,44 @@
+import { optional, z } from "zod";
+import { AIAgent } from "../../agents/ai-agent.js";
+import { isNil, omitBy } from "../../utils/type-utils.js";
+const COMPACTOR_INSTRUCTIONS = `\
+You are a conversation summarizer. Your task is to create a concise but comprehensive summary of the conversation history provided.
+
+## Conversation history
+
+${"```"}yaml alt="previous-summary"
+{{ previousSummary | yaml.stringify }}
+${"```"}
+
+
+${"```"}yaml alt="conversation-histories"
+{{ messages | yaml.stringify }}
+${"```"}
+
+## Guidelines
+
+1. Preserve key information, decisions, and context that would be needed for future conversation continuity
+2. Include important facts, names, dates, and specific details mentioned
+3. Summarize the user's goals and preferences expressed in the conversation
+4. Note any pending tasks or follow-up items
+5. Keep the summary focused and avoid unnecessary verbosity
+6. Write in a neutral, factual tone
+
+Output a single summary that captures the essence of the conversation.`;
+export class AISessionCompactor extends AIAgent {
+    constructor(options) {
+        super({
+            name: "SessionCompactor",
+            description: "Generates conversation summaries for session compaction",
+            inputSchema: z.object({
+                previousSummary: optional(z.array(z.string()).describe("List of previous conversation summaries")),
+                messages: z.array(z.any()),
+            }),
+            outputSchema: z.object({
+                summary: z.string().describe("A comprehensive summary of the conversation history"),
+            }),
+            instructions: COMPACTOR_INSTRUCTIONS,
+            ...omitBy(options ?? {}, (v) => isNil(v)),
+        });
+    }
+}

package/lib/esm/prompt/compact/types.d.ts

@@ -0,0 +1,79 @@
+import type { Agent, Message } from "../../agents/agent.js";
+import type { ChatModelInputMessage } from "../../agents/chat-model.js";
+/**
+ * Default compaction mode
+ */
+export declare const DEFAULT_COMPACT_MODE: "auto";
+/**
+ * Default maximum tokens before triggering compaction
+ */
+export declare const DEFAULT_MAX_TOKENS = 80000;
+/**
+ * Default ratio of maxTokens to reserve for keeping recent messages
+ */
+export declare const DEFAULT_KEEP_RECENT_RATIO = 0.5;
+/**
+ * Default async mode for compaction
+ */
+export declare const DEFAULT_COMPACT_ASYNC = true;
+/**
+ * Content structure for history entries
+ */
+export interface EntryContent {
+    input?: unknown;
+    output?: unknown;
+    messages?: ChatModelInputMessage[];
+}
+/**
+ * Output structure from the compactor agent
+ */
+export interface CompactContent extends Message {
+    summary: string;
+}
+/**
+ * Input structure for the compactor agent
+ */
+export interface CompactorInput extends Message {
+    previousSummary?: string[];
+    messages: ChatModelInputMessage[];
+}
+/**
+ * Type alias for a compactor agent
+ */
+export type Compactor = Agent<CompactorInput, CompactContent>;
+/**
+ * Configuration for session compaction
+ */
+export interface CompactConfig {
+    /**
+     * Compaction mode
+     * @default DEFAULT_COMPACT_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Maximum tokens before triggering compaction
+     * @default DEFAULT_MAX_TOKENS (80000)
+     */
+    maxTokens?: number;
+    /**
+     * Ratio of maxTokens to reserve for keeping recent messages (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * preserving recent conversation history without compaction.
+     *
+     * @default 0.5 (50% of maxTokens)
+     * @example 0.5 means if maxTokens=80000, keep up to 40000 tokens of recent messages
+     */
+    keepRecentRatio?: number;
+    /**
+     * Whether to perform compaction asynchronously
+     * @default DEFAULT_COMPACT_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that generates summaries from conversation entries
+     * Input: { entries: EntryContent[] }
+     * Output: { summary: string }
+     */
+    compactor?: Compactor;
+}

package/lib/esm/prompt/compact/types.js

@@ -0,0 +1,16 @@
+/**
+ * Default compaction mode
+ */
+export const DEFAULT_COMPACT_MODE = "auto";
+/**
+ * Default maximum tokens before triggering compaction
+ */
+export const DEFAULT_MAX_TOKENS = 80000;
+/**
+ * Default ratio of maxTokens to reserve for keeping recent messages
+ */
+export const DEFAULT_KEEP_RECENT_RATIO = 0.5;
+/**
+ * Default async mode for compaction
+ */
+export const DEFAULT_COMPACT_ASYNC = true;

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,7 +8,8 @@ export async function getHistories(agent) {
     if (!historyModule)
         return [];
     const history = (await afs.list(historyModule.path, {
-        limit: agent.historyConfig?.maxItems || 10,
+        filter,
+        limit: 10,
         orderBy: [["createdAt", "desc"]],
     })).data;
     return history

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,17 @@
 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, ChatModelInput, ChatModelInputMessage } from "../agents/chat-model.js";
 import { type FileUnionContent } from "../agents/model.js";
+import type { Context } from "../aigne/context.js";
+import { AgentSession } from "./agent-session.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;
@@ -26,7 +29,9 @@ export declare class PromptBuilder {
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
     copy(): PromptBuilder;
-    build(options: PromptBuildOptions): Promise<ChatModelInput & {
+    build(options: PromptBuildOptions): Promise<Omit<ChatModelInput, "messages"> & {
+        session: AgentSession;
+        userMessage: ChatModelInputMessage;
         toolAgents?: Agent[];
     }>;
     buildPrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
@@ -37,11 +42,8 @@ export declare class PromptBuilder {
     }>;
     private getTemplateVariables;
     private buildMessages;
-    getHistories(options: PromptBuildOptions): Promise<{
-        role: "user" | "agent";
-        content: unknown;
-    }[]>;
-    private refineMessages;
+    private mergeMessages;
+    protected deprecatedMemories(message: string | undefined, options: PromptBuildOptions): Promise<ChatModelInputMessage[]>;
     private convertMemoriesToMessages;
     private buildResponseFormat;
     private buildTools;