@falai/agent 1.1.3 → 1.2.0

package/dist/core/CompactionEngine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CompactionEngine - Manages conversation history size through multi-layered compaction strategies.
+ *
+ * Strategies are applied in order of cost:
+ * 1. none - history is under threshold, no action needed
+ * 2. tool_result_budget - truncate oversized tool results (no LLM call)
+ * 3. micro_compact - compress verbose tool outputs inline (no LLM call)
+ * 4. auto_compact - summarize old messages via LLM provider
+ */
+import type { HistoryItem } from "../types/history";
+import type { CompactionOptions, CompactionResult } from "../types/compaction";
+export declare class CompactionEngine {
+    /**
+     * Validate CompactionOptions. Throws on invalid values.
+     */
+    static validateOptions(options: CompactionOptions): void;
+    /**
+     * Estimate token count using a character-based heuristic (~4 chars/token).
+     *
+     * For each HistoryItem: count content length + name length (if present) + 4 (role overhead).
+     * Returns Math.ceil(totalChars / 4). Empty history returns 0.
+     * Deterministic for the same input.
+     */
+    static estimateTokens(history: HistoryItem[]): number;
+    /**
+     * Truncate tool results that exceed the per-message character budget.
+     *
+     * For HistoryItem with role === 'tool' whose content exceeds maxChars,
+     * truncate to maxChars and append truncation notice.
+     * Items within budget are returned unchanged.
+     */
+    static applyToolResultBudget(history: HistoryItem[], maxCharsPerResult: number): HistoryItem[];
+    /**
+     * Micro-compact: compress verbose tool outputs inline.
+     * Strips excessive whitespace and shortens JSON-like content in tool results.
+     * Preserves the last `preserveCount` messages unchanged.
+     */
+    private static microCompact;
+    /**
+     * Count how many messages differ between original and compacted history.
+     */
+    private static countDifferences;
+    /**
+     * Summarize old messages via LLM provider.
+     * On failure, returns null (caller should fall back).
+     */
+    private static summarizeMessages;
+    /**
+     * Aggressive truncation fallback: remove oldest messages (no LLM needed).
+     * Keeps only the most recent messages that fit within the token budget.
+     */
+    private static aggressiveTruncate;
+    /**
+     * Multi-layered compaction strategy.
+     *
+     * Layer 1 (none): If estimatedTokens < maxTokens * compactionThreshold, return unchanged
+     * Layer 2 (tool_result_budget): Apply applyToolResultBudget, check if under threshold
+     * Layer 3 (micro_compact): Compress verbose tool outputs inline
+     * Layer 4 (auto_compact): Summarize old messages via LLM provider
+     *
+     * The last `preserveRecentCount` messages are NEVER modified or removed.
+     */
+    static checkAndCompact(history: HistoryItem[], options: CompactionOptions): Promise<CompactionResult>;
+}
+//# sourceMappingURL=CompactionEngine.d.ts.map

package/dist/core/CompactionEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompactionEngine.d.ts","sourceRoot":"","sources":["../../src/core/CompactionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE/E,qBAAa,gBAAgB;IACzB;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IA4BxD;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM;IAiBrD;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,iBAAiB,EAAE,MAAM,GAC1B,WAAW,EAAE;IAkBhB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IA2B3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B;;;OAGG;mBACkB,iBAAiB;IA+BtC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA2BjC;;;;;;;;;OASG;WACU,eAAe,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;CA2F/B"}

package/dist/core/CompactionEngine.js

@@ -0,0 +1,244 @@
+/**
+ * CompactionEngine - Manages conversation history size through multi-layered compaction strategies.
+ *
+ * Strategies are applied in order of cost:
+ * 1. none - history is under threshold, no action needed
+ * 2. tool_result_budget - truncate oversized tool results (no LLM call)
+ * 3. micro_compact - compress verbose tool outputs inline (no LLM call)
+ * 4. auto_compact - summarize old messages via LLM provider
+ */
+import log from "loglevel";
+export class CompactionEngine {
+    /**
+     * Validate CompactionOptions. Throws on invalid values.
+     */
+    static validateOptions(options) {
+        if (typeof options.compactionThreshold !== "number" ||
+            options.compactionThreshold < 0.5 ||
+            options.compactionThreshold > 0.95) {
+            throw new Error(`compactionThreshold must be between 0.5 and 0.95, got ${options.compactionThreshold}`);
+        }
+        if (typeof options.preserveRecentCount !== "number" ||
+            options.preserveRecentCount < 2) {
+            throw new Error(`preserveRecentCount must be >= 2, got ${options.preserveRecentCount}`);
+        }
+        if (typeof options.maxToolResultChars !== "number" ||
+            options.maxToolResultChars <= 0) {
+            throw new Error(`maxToolResultChars must be > 0, got ${options.maxToolResultChars}`);
+        }
+    }
+    /**
+     * Estimate token count using a character-based heuristic (~4 chars/token).
+     *
+     * For each HistoryItem: count content length + name length (if present) + 4 (role overhead).
+     * Returns Math.ceil(totalChars / 4). Empty history returns 0.
+     * Deterministic for the same input.
+     */
+    static estimateTokens(history) {
+        if (history.length === 0)
+            return 0;
+        let totalChars = 0;
+        for (const item of history) {
+            const content = item.content;
+            const contentLength = typeof content === "string" ? content.length : JSON.stringify(content ?? "").length;
+            totalChars += contentLength;
+            if ("name" in item && typeof item.name === "string") {
+                totalChars += item.name.length;
+            }
+            totalChars += 4; // role overhead
+        }
+        return Math.ceil(totalChars / 4);
+    }
+    /**
+     * Truncate tool results that exceed the per-message character budget.
+     *
+     * For HistoryItem with role === 'tool' whose content exceeds maxChars,
+     * truncate to maxChars and append truncation notice.
+     * Items within budget are returned unchanged.
+     */
+    static applyToolResultBudget(history, maxCharsPerResult) {
+        return history.map((item) => {
+            if (item.role !== "tool")
+                return item;
+            const contentStr = typeof item.content === "string"
+                ? item.content
+                : JSON.stringify(item.content ?? "");
+            const totalChars = contentStr.length;
+            if (totalChars <= maxCharsPerResult)
+                return item;
+            const preview = contentStr.slice(0, maxCharsPerResult);
+            const truncatedContent = `${preview}\n\n[Truncated: ${totalChars} chars total, showing first ${maxCharsPerResult}]`;
+            return { ...item, content: truncatedContent };
+        });
+    }
+    /**
+     * Micro-compact: compress verbose tool outputs inline.
+     * Strips excessive whitespace and shortens JSON-like content in tool results.
+     * Preserves the last `preserveCount` messages unchanged.
+     */
+    static microCompact(history, preserveCount) {
+        const cutoff = Math.max(0, history.length - preserveCount);
+        const compactable = history.slice(0, cutoff);
+        const preserved = history.slice(cutoff);
+        const compacted = compactable.map((item) => {
+            if (item.role !== "tool")
+                return item;
+            const contentStr = typeof item.content === "string"
+                ? item.content
+                : JSON.stringify(item.content ?? "");
+            // Strip excessive whitespace: collapse runs of whitespace to single space
+            const compressed = contentStr
+                .replace(/\s+/g, " ")
+                .trim();
+            return { ...item, content: compressed };
+        });
+        return [...compacted, ...preserved];
+    }
+    /**
+     * Count how many messages differ between original and compacted history.
+     */
+    static countDifferences(original, compacted) {
+        let count = 0;
+        const len = Math.min(original.length, compacted.length);
+        for (let i = 0; i < len; i++) {
+            if (original[i] !== compacted[i])
+                count++;
+        }
+        // If lengths differ, count the extra messages
+        count += Math.abs(original.length - compacted.length);
+        return count;
+    }
+    /**
+     * Summarize old messages via LLM provider.
+     * On failure, returns null (caller should fall back).
+     */
+    static async summarizeMessages(messages, options) {
+        try {
+            const messagesText = messages
+                .map((m) => {
+                const content = typeof m.content === "string"
+                    ? m.content
+                    : JSON.stringify(m.content ?? "");
+                return `[${m.role}]: ${content}`;
+            })
+                .join("\n");
+            const result = await options.provider.generateMessage({
+                prompt: `Summarize the following conversation concisely, preserving key facts, decisions, and context:\n\n${messagesText}`,
+                history: [],
+                context: {},
+                parameters: {
+                    maxOutputTokens: 1024,
+                    jsonSchema: {},
+                },
+            });
+            return result.message;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Aggressive truncation fallback: remove oldest messages (no LLM needed).
+     * Keeps only the most recent messages that fit within the token budget.
+     */
+    static aggressiveTruncate(history, options) {
+        const threshold = options.maxTokens * options.compactionThreshold;
+        const preserveCount = options.preserveRecentCount;
+        // Always preserve the last preserveRecentCount messages
+        const preserved = history.slice(-preserveCount);
+        // Try to keep as many older messages as fit within budget
+        const older = history.slice(0, -preserveCount);
+        const result = [];
+        // Add older messages from most recent backwards until we'd exceed budget
+        for (let i = older.length - 1; i >= 0; i--) {
+            const candidate = [older[i], ...result, ...preserved];
+            if (CompactionEngine.estimateTokens(candidate) < threshold) {
+                result.unshift(older[i]);
+            }
+            else {
+                break;
+            }
+        }
+        return [...result, ...preserved];
+    }
+    /**
+     * Multi-layered compaction strategy.
+     *
+     * Layer 1 (none): If estimatedTokens < maxTokens * compactionThreshold, return unchanged
+     * Layer 2 (tool_result_budget): Apply applyToolResultBudget, check if under threshold
+     * Layer 3 (micro_compact): Compress verbose tool outputs inline
+     * Layer 4 (auto_compact): Summarize old messages via LLM provider
+     *
+     * The last `preserveRecentCount` messages are NEVER modified or removed.
+     */
+    static async checkAndCompact(history, options) {
+        CompactionEngine.validateOptions(options);
+        const threshold = options.maxTokens * options.compactionThreshold;
+        const estimatedTokens = CompactionEngine.estimateTokens(history);
+        // Layer 1: No compaction needed
+        if (estimatedTokens < threshold) {
+            return {
+                history,
+                strategy: "none",
+                estimatedTokens,
+                messagesCompacted: 0,
+            };
+        }
+        // Layer 2: Tool result budgeting (cheapest — no LLM call)
+        // Apply budget but preserve recent messages
+        const preserveCount = Math.min(options.preserveRecentCount, history.length);
+        const cutoff2 = Math.max(0, history.length - preserveCount);
+        const budgeted = [
+            ...CompactionEngine.applyToolResultBudget(history.slice(0, cutoff2), options.maxToolResultChars),
+            ...history.slice(cutoff2),
+        ];
+        let newEstimate = CompactionEngine.estimateTokens(budgeted);
+        if (newEstimate < threshold) {
+            return {
+                history: budgeted,
+                strategy: "tool_result_budget",
+                estimatedTokens: newEstimate,
+                messagesCompacted: CompactionEngine.countDifferences(history, budgeted),
+            };
+        }
+        // Layer 3: Micro-compaction (compress verbose tool outputs)
+        const microCompacted = CompactionEngine.microCompact(budgeted, preserveCount);
+        newEstimate = CompactionEngine.estimateTokens(microCompacted);
+        if (newEstimate < threshold) {
+            return {
+                history: microCompacted,
+                strategy: "micro_compact",
+                estimatedTokens: newEstimate,
+                messagesCompacted: CompactionEngine.countDifferences(history, microCompacted),
+            };
+        }
+        // Layer 4: Auto-compact (summarize old messages via LLM)
+        const oldMessages = microCompacted.slice(0, -preserveCount);
+        const recentMessages = microCompacted.slice(-preserveCount);
+        const summary = await CompactionEngine.summarizeMessages(oldMessages, options);
+        if (summary !== null) {
+            const summaryItem = {
+                role: "system",
+                content: `[Conversation Summary]\n${summary}`,
+            };
+            const finalHistory = [summaryItem, ...recentMessages];
+            return {
+                history: finalHistory,
+                strategy: "auto_compact",
+                estimatedTokens: CompactionEngine.estimateTokens(finalHistory),
+                messagesCompacted: oldMessages.length,
+                summary,
+            };
+        }
+        // Fallback: LLM summarization failed — aggressive truncation
+        log.warn("CompactionEngine: LLM summarization failed, falling back to aggressive truncation");
+        const truncated = CompactionEngine.aggressiveTruncate(microCompacted, options);
+        return {
+            history: truncated,
+            strategy: "auto_compact",
+            estimatedTokens: CompactionEngine.estimateTokens(truncated),
+            messagesCompacted: history.length - truncated.length,
+        };
+    }
+}
+//# sourceMappingURL=CompactionEngine.js.map

package/dist/core/CompactionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompactionEngine.js","sourceRoot":"","sources":["../../src/core/CompactionEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/PromptComposer.d.ts

@@ -1,14 +1,21 @@
 import type { Event, Term, Guideline, AgentOptions } from "../types";
 import type { Route } from "./Route";
 import { TemplateContext } from "../types/template";
+import { PromptSectionCache } from "./PromptSectionCache";
 export declare class PromptComposer<TContext = unknown, TData = unknown> {
     private parts;
     private renderContext;
-    constructor(context?: TemplateContext<TContext, TData>);
+    private cache;
+    private instructionCounter;
+    constructor(context?: TemplateContext<TContext, TData>, cache?: PromptSectionCache);
     addAgentMeta(agent: AgentOptions<TContext, TData>): Promise<this>;
     addRoutingOverview(routes: Route<TContext, TData>[]): Promise<this>;
     addScoringRules(): Promise<this>;
     addInstruction(text: string): Promise<this>;
+    /**
+     * @deprecated History should flow through `GenerateMessageInput.history` natively.
+     * This method is kept for backward compatibility but will be removed in a future version.
+     */
     addInteractionHistory(history: Event[], note?: string): Promise<this>;
     addLastMessage(message: string): Promise<this>;
     addGlossary(terms: Term<TContext>[]): Promise<this>;

package/dist/core/PromptComposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PromptComposer.d.ts","sourceRoot":"","sources":["../../src/core/PromptComposer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,qBAAa,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO;IAC7D,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAmC;gBAE5C,OAAO,GAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAA6B;IAM3E,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4CjE,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAchC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,qBAAqB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYrE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnD,aAAa,CAAC,UAAU,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDtE,gBAAgB,CACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC;IAgBV,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqChE,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD,iBAAiB,CACrB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC;IAeV,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAI/B"}
+{"version":3,"file":"PromptComposer.d.ts","sourceRoot":"","sources":["../../src/core/PromptComposer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,qBAAa,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO;IAC7D,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,kBAAkB,CAAK;gBAG7B,OAAO,GAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAA6B,EACrE,KAAK,CAAC,EAAE,kBAAkB;IAQtB,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDjE,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBhC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjD;;;OAGG;IACG,qBAAqB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BnD,aAAa,CAAC,UAAU,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiEtE,gBAAgB,CACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC;IAwBV,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6ChE,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnD,iBAAiB,CACrB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC;IAsBV,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAY/B"}