@lleverage-ai/agent-sdk 0.0.1

package/dist/context-manager.js

@@ -0,0 +1,1039 @@
+/**
+ * Context management for token tracking and auto-compaction.
+ *
+ * This module provides tools for managing conversation context, including:
+ * - Token counting and budget tracking
+ * - Automatic context compaction/summarization
+ * - Message history management
+ *
+ * @packageDocumentation
+ */
+/**
+ * Helper function to create a hash for a message for caching purposes.
+ * Uses a simple hash of the serialized message content.
+ *
+ * @param message - The message to hash
+ * @returns A hash string for the message
+ */
+function hashMessage(message) {
+    // Create a stable string representation
+    let content;
+    if (typeof message.content === "string") {
+        content = message.content;
+    }
+    else if (Array.isArray(message.content)) {
+        // For array content, create a hash-friendly representation
+        // For images/files, include type and a marker (not the full data)
+        content = message.content
+            .map((part) => {
+            if ("text" in part)
+                return `text:${part.text}`;
+            if ("image" in part)
+                return `image:${part.type}`;
+            if ("data" in part && part.type === "file")
+                return `file:${part.type}`;
+            if ("toolName" in part)
+                return `tool:${part.toolName}`;
+            if ("result" in part)
+                return `result:${JSON.stringify(part.result)}`;
+            if ("output" in part)
+                return `output:${JSON.stringify(part.output)}`;
+            return JSON.stringify(part);
+        })
+            .join("|");
+    }
+    else {
+        content = JSON.stringify(message.content);
+    }
+    // Simple hash function (djb2)
+    let hash = 5381;
+    for (let i = 0; i < content.length; i++) {
+        hash = (hash << 5) + hash + content.charCodeAt(i); /* hash * 33 + c */
+    }
+    return `${message.role}:${hash}`;
+}
+/**
+ * Creates a simple token counter using character approximation.
+ *
+ * Uses the common approximation of 4 characters per token.
+ * This is faster but less accurate than model-specific tokenizers.
+ * Includes a message-level cache to avoid re-counting identical messages.
+ *
+ * @returns A token counter using character approximation
+ *
+ * @example
+ * ```typescript
+ * const counter = createApproximateTokenCounter();
+ * const tokens = counter.count("Hello, world!"); // ~3 tokens
+ * ```
+ *
+ * @category Context
+ */
+export function createApproximateTokenCounter() {
+    const CHARS_PER_TOKEN = 4;
+    const messageCache = new Map();
+    const count = (text) => {
+        return Math.ceil(text.length / CHARS_PER_TOKEN);
+    };
+    const countSingleMessage = (message) => {
+        const hash = hashMessage(message);
+        // Check cache
+        const cached = messageCache.get(hash);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let total = 0;
+        // Count message overhead (role, structure)
+        total += 4; // Approximate overhead per message
+        // Count content
+        if (typeof message.content === "string") {
+            total += count(message.content);
+        }
+        else if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if ("text" in part && typeof part.text === "string") {
+                    total += count(part.text);
+                }
+                else if ("toolName" in part) {
+                    // Tool call - count name and args
+                    total += count(part.toolName);
+                    if ("args" in part) {
+                        total += count(JSON.stringify(part.args));
+                    }
+                    if ("input" in part) {
+                        total += count(JSON.stringify(part.input));
+                    }
+                }
+                else if ("result" in part || "output" in part) {
+                    // Tool result - count output
+                    const output = "result" in part ? part.result : part.output;
+                    total += count(typeof output === "string" ? output : JSON.stringify(output));
+                }
+                else if ("image" in part) {
+                    // Image part - count ~1000 tokens for image (approximate vision model cost)
+                    // Images are expensive in terms of tokens, varies by size and model
+                    total += 1000;
+                }
+                else if ("data" in part && part.type === "file") {
+                    // File part - count as ~500 tokens per file (placeholder)
+                    // Actual token count depends on file size and content
+                    total += 500;
+                }
+            }
+        }
+        // Store in cache
+        messageCache.set(hash, total);
+        return total;
+    };
+    const countMessages = (messages) => {
+        let total = 0;
+        for (const message of messages) {
+            total += countSingleMessage(message);
+        }
+        return total;
+    };
+    const invalidateCache = () => {
+        messageCache.clear();
+    };
+    return { count, countMessages, invalidateCache };
+}
+/**
+ * Creates a token counter with a custom counting function.
+ *
+ * Use this to integrate model-specific tokenizers for more accurate counts.
+ * Includes a message-level cache to avoid re-counting identical messages.
+ *
+ * @param options - Configuration for the token counter
+ * @returns A token counter using the custom function
+ *
+ * @example
+ * ```typescript
+ * import { encoding_for_model } from "tiktoken";
+ *
+ * const encoder = encoding_for_model("gpt-4");
+ * const counter = createCustomTokenCounter({
+ *   countFn: (text) => encoder.encode(text).length,
+ * });
+ * ```
+ *
+ * @category Context
+ */
+export function createCustomTokenCounter(options) {
+    const { countFn, messageOverhead = 4 } = options;
+    const messageCache = new Map();
+    const countSingleMessage = (message) => {
+        const hash = hashMessage(message);
+        // Check cache
+        const cached = messageCache.get(hash);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let total = messageOverhead;
+        if (typeof message.content === "string") {
+            total += countFn(message.content);
+        }
+        else if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if ("text" in part && typeof part.text === "string") {
+                    total += countFn(part.text);
+                }
+                else if ("toolName" in part) {
+                    total += countFn(part.toolName);
+                    if ("args" in part) {
+                        total += countFn(JSON.stringify(part.args));
+                    }
+                    if ("input" in part) {
+                        total += countFn(JSON.stringify(part.input));
+                    }
+                }
+                else if ("result" in part || "output" in part) {
+                    const output = "result" in part ? part.result : part.output;
+                    total += countFn(typeof output === "string" ? output : JSON.stringify(output));
+                }
+                else if ("image" in part) {
+                    // Image part - count ~1000 tokens for image (approximate vision model cost)
+                    // Images are expensive in terms of tokens, varies by size and model
+                    total += 1000;
+                }
+                else if ("data" in part && part.type === "file") {
+                    // File part - count as ~500 tokens per file (placeholder)
+                    // Actual token count depends on file size and content
+                    total += 500;
+                }
+            }
+        }
+        // Store in cache
+        messageCache.set(hash, total);
+        return total;
+    };
+    const countMessages = (messages) => {
+        let total = 0;
+        for (const message of messages) {
+            total += countSingleMessage(message);
+        }
+        return total;
+    };
+    const invalidateCache = () => {
+        messageCache.clear();
+    };
+    return { count: countFn, countMessages, invalidateCache };
+}
+/**
+ * Creates a token budget from current usage.
+ *
+ * @param maxTokens - Maximum tokens allowed
+ * @param currentTokens - Current token count
+ * @param isActual - Whether this is based on actual model usage (default: false)
+ * @returns A token budget object
+ *
+ * @category Context
+ */
+export function createTokenBudget(maxTokens, currentTokens, isActual = false) {
+    return {
+        maxTokens,
+        currentTokens,
+        usage: currentTokens / maxTokens,
+        remaining: Math.max(0, maxTokens - currentTokens),
+        isActual,
+    };
+}
+/**
+ * Default compaction policy.
+ *
+ * @category Context
+ */
+export const DEFAULT_COMPACTION_POLICY = {
+    enabled: true,
+    tokenThreshold: 0.8,
+    hardCapThreshold: 0.95,
+    enableGrowthRatePrediction: false,
+    enableErrorFallback: true,
+};
+/**
+ * Default summarization configuration.
+ *
+ * @category Context
+ */
+export const DEFAULT_SUMMARIZATION_CONFIG = {
+    keepMessageCount: 10,
+    keepToolResultCount: 5,
+    strategy: "rollup",
+    enableTieredSummaries: false,
+    maxSummaryTiers: 3,
+    messagesPerTier: 5,
+    enableStructuredSummary: false,
+};
+/**
+ * Creates a compaction scheduler for managing background compaction tasks.
+ *
+ * @param contextManager - The context manager to use for compaction
+ * @param options - Scheduler configuration options
+ * @returns A compaction scheduler instance
+ *
+ * @example
+ * ```typescript
+ * const scheduler = createCompactionScheduler(contextManager, {
+ *   enableBackgroundCompaction: true,
+ *   debounceDelayMs: 5000,
+ *   onTaskComplete: (task) => {
+ *     console.log(`Compaction saved ${task.result?.tokensBefore - task.result?.tokensAfter} tokens`);
+ *   },
+ * });
+ *
+ * // Schedule a compaction
+ * const taskId = scheduler.schedule(messages, agent, "token_threshold");
+ *
+ * // Later, get the result
+ * const result = scheduler.getLatestResult();
+ * if (result) {
+ *   messages = result.newMessages;
+ * }
+ * ```
+ *
+ * @category Context
+ */
+export function createCompactionScheduler(contextManager, options = {}) {
+    const { enableBackgroundCompaction = false, debounceDelayMs = 5000, maxPendingTasks = 3, onTaskComplete, onTaskError, } = options;
+    const tasks = new Map();
+    const taskAgents = new Map(); // Store agents for each task
+    let taskIdCounter = 0;
+    let debounceTimer = null;
+    let isShutdown = false;
+    const schedule = (messages, agent, trigger) => {
+        if (isShutdown) {
+            throw new Error("Scheduler has been shut down");
+        }
+        if (!enableBackgroundCompaction) {
+            // When background compaction is disabled, return a placeholder ID
+            // The caller should handle compaction synchronously
+            return `sync-${Date.now()}`;
+        }
+        const taskId = `task-${++taskIdCounter}`;
+        const task = {
+            id: taskId,
+            status: "pending",
+            messages: [...messages], // Clone to avoid mutation
+            createdAt: Date.now(),
+            trigger,
+        };
+        // Enforce max pending tasks - drop oldest pending task
+        const pendingTasks = Array.from(tasks.values())
+            .filter((t) => t.status === "pending")
+            .sort((a, b) => a.createdAt - b.createdAt);
+        if (pendingTasks.length >= maxPendingTasks) {
+            const oldestTask = pendingTasks[0];
+            if (oldestTask) {
+                tasks.delete(oldestTask.id);
+            }
+        }
+        tasks.set(taskId, task);
+        taskAgents.set(taskId, agent); // Store agent for this task
+        // Debounce execution
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(() => {
+            executeNextTask();
+            debounceTimer = null;
+        }, debounceDelayMs);
+        return taskId;
+    };
+    const executeNextTask = async () => {
+        if (isShutdown) {
+            return;
+        }
+        // Find the oldest pending task
+        const pendingTask = Array.from(tasks.values())
+            .filter((t) => t.status === "pending")
+            .sort((a, b) => a.createdAt - b.createdAt)[0];
+        if (!pendingTask) {
+            return;
+        }
+        // Get the agent for this task
+        const agent = taskAgents.get(pendingTask.id);
+        if (!agent) {
+            // This shouldn't happen, but handle gracefully
+            pendingTask.status = "failed";
+            pendingTask.completedAt = Date.now();
+            pendingTask.error = new Error("Agent not found for task");
+            onTaskError?.(pendingTask);
+            return;
+        }
+        // Mark as running
+        pendingTask.status = "running";
+        pendingTask.startedAt = Date.now();
+        try {
+            // Execute compaction
+            const result = await contextManager.compact(pendingTask.messages, agent, pendingTask.trigger);
+            // Mark as completed
+            pendingTask.status = "completed";
+            pendingTask.completedAt = Date.now();
+            pendingTask.result = result;
+            onTaskComplete?.(pendingTask);
+        }
+        catch (error) {
+            // Mark as failed
+            pendingTask.status = "failed";
+            pendingTask.completedAt = Date.now();
+            pendingTask.error = error instanceof Error ? error : new Error(String(error));
+            onTaskError?.(pendingTask);
+        }
+        // Execute next task if any
+        const hasMorePending = Array.from(tasks.values()).some((t) => t.status === "pending");
+        if (hasMorePending) {
+            // Schedule next task with debounce
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+            }
+            debounceTimer = setTimeout(() => {
+                executeNextTask();
+                debounceTimer = null;
+            }, debounceDelayMs);
+        }
+    };
+    const getTask = (id) => {
+        return tasks.get(id);
+    };
+    const getPendingTasks = () => {
+        return Array.from(tasks.values())
+            .filter((t) => t.status === "pending")
+            .sort((a, b) => a.createdAt - b.createdAt);
+    };
+    const getLatestResult = () => {
+        // Find the most recent completed task
+        const completedTasks = Array.from(tasks.values())
+            .filter((t) => t.status === "completed" && t.result)
+            .sort((a, b) => (b.completedAt ?? 0) - (a.completedAt ?? 0));
+        return completedTasks[0]?.result;
+    };
+    const cancel = (id) => {
+        const task = tasks.get(id);
+        if (!task || task.status !== "pending") {
+            return false;
+        }
+        tasks.delete(id);
+        taskAgents.delete(id); // Clean up agent reference
+        return true;
+    };
+    const cleanup = () => {
+        // Remove completed and failed tasks
+        for (const [id, task] of tasks.entries()) {
+            if (task.status === "completed" || task.status === "failed") {
+                tasks.delete(id);
+                taskAgents.delete(id); // Clean up agent reference
+            }
+        }
+    };
+    const shutdown = () => {
+        isShutdown = true;
+        // Clear debounce timer
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        // Cancel all pending tasks
+        for (const [_id, task] of tasks.entries()) {
+            if (task.status === "pending") {
+                task.status = "failed";
+                task.error = new Error("Scheduler shut down");
+                task.completedAt = Date.now();
+            }
+        }
+    };
+    return {
+        schedule,
+        getTask,
+        getPendingTasks,
+        getLatestResult,
+        cancel,
+        cleanup,
+        shutdown,
+    };
+}
+/**
+ * Default prompt for generating conversation summaries.
+ */
+const DEFAULT_SUMMARY_PROMPT = `You are summarizing a conversation for context management. Create a concise summary that:
+
+1. Preserves key decisions, facts, and user preferences
+2. Maintains important technical details and code references
+3. Notes any pending tasks or unresolved questions
+4. Captures references to images, files, and media (e.g., "discussed screenshot of X", "analyzed document Y")
+5. Uses bullet points for clarity
+6. Is approximately 200-500 words
+
+Do not include:
+- Pleasantries or greetings
+- Redundant information
+- Tool call details (just outcomes)
+- Verbose explanations
+- Full image/file contents (just references and context)
+
+Format:
+## Conversation Summary
+[Your summary here]`;
+/**
+ * Prompt for generating structured summaries with sections.
+ */
+const STRUCTURED_SUMMARY_PROMPT = `You are summarizing a conversation for context management. Generate a structured summary in JSON format with the following sections:
+
+{
+  "decisions": ["Key decision 1", "Key decision 2", ...],
+  "preferences": ["User preference 1", "User preference 2", ...],
+  "currentState": ["Current state fact 1", "Current state fact 2", ...],
+  "openQuestions": ["Unresolved question 1", "Unresolved question 2", ...],
+  "references": ["file.ts:123", "userId: abc123", "URL: https://...", "Image: screenshot.png showing X", "File: document.pdf containing Y", ...]
+}
+
+Guidelines:
+- **decisions**: Important choices made (architecture, approach, tools)
+- **preferences**: User requirements, constraints, style preferences
+- **currentState**: What's been implemented, current progress, known issues
+- **openQuestions**: Unresolved issues, pending decisions, items to revisit
+- **references**: File paths, identifiers, URLs, config values, images, documents that may be needed later
+
+Keep each item concise (1-2 sentences). Focus on information that will be useful for continuing the conversation.
+For images and files, include what they contained or depicted, not just that they were present.
+Respond ONLY with valid JSON, no additional text.`;
+/**
+ * Prompt for generating tiered summaries (summary of summaries).
+ */
+const TIERED_SUMMARY_PROMPT = `You are creating a higher-level summary from multiple conversation summaries. Consolidate the key information from these summaries:
+
+Guidelines:
+1. Merge related decisions and facts
+2. Preserve the most important details
+3. Remove redundancy across summaries
+4. Maintain chronological context where relevant
+5. Keep the summary concise but comprehensive
+
+Format:
+## Tiered Summary (Level {tier})
+[Your consolidated summary here]`;
+/**
+ * Creates a context manager for tracking and managing conversation context.
+ *
+ * @param options - Configuration options
+ * @returns A context manager instance
+ *
+ * @example
+ * ```typescript
+ * const contextManager = createContextManager({
+ *   maxTokens: 100000,
+ *   summarization: {
+ *     tokenThreshold: 0.75,
+ *     keepMessageCount: 15,
+ *   },
+ *   onBudgetUpdate: (budget) => {
+ *     console.log(`Context usage: ${(budget.usage * 100).toFixed(1)}%`);
+ *   },
+ * });
+ *
+ * // Check budget
+ * const budget = contextManager.getBudget(messages);
+ *
+ * // Process messages (auto-compacts if needed)
+ * const processedMessages = await contextManager.process(messages, agent);
+ * ```
+ *
+ * @category Context
+ */
+export function createContextManager(options) {
+    const tokenCounter = options.tokenCounter ?? createApproximateTokenCounter();
+    const policy = {
+        ...DEFAULT_COMPACTION_POLICY,
+        ...options.policy,
+    };
+    const summarizationConfig = {
+        ...DEFAULT_SUMMARIZATION_CONFIG,
+        ...options.summarization,
+    };
+    const { maxTokens, onBudgetUpdate, onCompact } = options;
+    // Track actual usage from model responses
+    let lastActualUsage = null;
+    // Track pinned messages
+    const pinnedMessages = [];
+    // Track summary tiers for tiered strategy
+    let currentSummaryTier = 0;
+    // Create scheduler if background compaction is enabled
+    let scheduler;
+    if (options.scheduler?.enableBackgroundCompaction) {
+        // We'll create the scheduler after defining the manager, to avoid circular dependency
+        // For now, set it to undefined and assign it later
+        scheduler = undefined;
+    }
+    const getBudget = (messages) => {
+        let currentTokens;
+        let isActual = false;
+        // If we have actual usage data from the last generation, use it
+        if (lastActualUsage && lastActualUsage.totalTokens !== undefined) {
+            currentTokens = lastActualUsage.totalTokens;
+            isActual = true;
+        }
+        else {
+            // Fall back to estimation
+            currentTokens = tokenCounter.countMessages(messages);
+        }
+        const budget = createTokenBudget(maxTokens, currentTokens, isActual);
+        onBudgetUpdate?.(budget);
+        return budget;
+    };
+    const shouldCompact = (messages) => {
+        if (!policy.enabled) {
+            return { trigger: false };
+        }
+        const budget = getBudget(messages);
+        // Custom policy override
+        if (policy.shouldCompact) {
+            return policy.shouldCompact(budget, messages);
+        }
+        // Hard cap safety - force compaction at 95% to prevent errors
+        if (budget.usage >= policy.hardCapThreshold) {
+            return { trigger: true, reason: "hard_cap" };
+        }
+        // Standard token threshold
+        if (budget.usage >= policy.tokenThreshold) {
+            return { trigger: true, reason: "token_threshold" };
+        }
+        // Growth rate prediction (simplified version)
+        if (policy.enableGrowthRatePrediction && messages.length >= 2) {
+            // Estimate growth: if last message was large relative to average
+            const lastMessage = messages[messages.length - 1];
+            if (lastMessage) {
+                const lastMessageTokens = tokenCounter.countMessages([lastMessage]);
+                const avgMessageTokens = budget.currentTokens / messages.length;
+                // If last message is significantly larger than average, predict growth
+                if (lastMessageTokens > avgMessageTokens * 2) {
+                    const predictedNext = budget.currentTokens + lastMessageTokens;
+                    const predictedUsage = predictedNext / maxTokens;
+                    if (predictedUsage >= policy.tokenThreshold) {
+                        return { trigger: true, reason: "growth_rate" };
+                    }
+                }
+            }
+        }
+        return { trigger: false };
+    };
+    const compact = async (messages, agent, trigger = "token_threshold") => {
+        const tokensBefore = tokenCounter.countMessages(messages);
+        const messagesBefore = messages.length;
+        const { keepMessageCount, strategy = "rollup", enableStructuredSummary, enableTieredSummaries, } = summarizationConfig;
+        // Always keep system messages
+        const systemMessages = messages.filter((m) => m.role === "system");
+        const _nonSystemMessages = messages.filter((m) => m.role !== "system");
+        // Filter out pinned messages (keep them separate)
+        // pinnedMessages indices refer to the original messages array
+        const pinnedIndices = new Set(pinnedMessages.map((p) => p.messageIndex));
+        const pinnedMessagesArray = [];
+        const unpinnedMessages = [];
+        messages.forEach((msg, idx) => {
+            // Skip system messages (already handled)
+            if (msg.role === "system")
+                return;
+            if (pinnedIndices.has(idx)) {
+                pinnedMessagesArray.push(msg);
+            }
+            else {
+                unpinnedMessages.push(msg);
+            }
+        });
+        // Keep recent messages from unpinned messages
+        const recentMessages = unpinnedMessages.slice(-keepMessageCount);
+        const oldMessages = unpinnedMessages.slice(0, Math.max(0, unpinnedMessages.length - keepMessageCount));
+        // If nothing to compact, return unchanged
+        if (oldMessages.length === 0) {
+            return {
+                messagesBefore,
+                messagesAfter: messages.length,
+                tokensBefore,
+                tokensAfter: tokensBefore,
+                summary: "",
+                compactedMessages: [],
+                newMessages: messages,
+                trigger,
+                strategy,
+            };
+        }
+        // Execute strategy-specific compaction
+        let summary;
+        let structuredSummary;
+        let summaryTier;
+        if (strategy === "tiered" && enableTieredSummaries) {
+            // Tiered strategy: check if we have existing summaries to tier
+            const existingSummaries = messages.filter((m) => m.role === "assistant" &&
+                typeof m.content === "string" &&
+                m.content.includes("[Previous conversation summary]"));
+            if (existingSummaries.length >= (summarizationConfig.messagesPerTier ?? 5)) {
+                // Create a higher-tier summary
+                currentSummaryTier++;
+                const summariesContent = existingSummaries.map((m) => m.content).join("\n\n");
+                const tierPrompt = TIERED_SUMMARY_PROMPT.replace("{tier}", String(currentSummaryTier));
+                const summaryResult = await agent.generate({
+                    messages: [
+                        { role: "system", content: tierPrompt },
+                        {
+                            role: "user",
+                            content: `Consolidate these summaries:\n\n${summariesContent}`,
+                        },
+                    ],
+                    maxTokens: 1000,
+                    _skipCompaction: true, // Prevent recursive compaction during summary generation
+                });
+                summary = summaryResult.status === "complete" ? summaryResult.text : "";
+                summaryTier = currentSummaryTier;
+            }
+            else {
+                // Create a first-tier summary
+                const contentToSummarize = formatMessagesForSummary(oldMessages);
+                const summaryPrompt = enableStructuredSummary
+                    ? STRUCTURED_SUMMARY_PROMPT
+                    : (summarizationConfig.summaryPrompt ?? DEFAULT_SUMMARY_PROMPT);
+                const summaryResult = await agent.generate({
+                    messages: [
+                        { role: "system", content: summaryPrompt },
+                        {
+                            role: "user",
+                            content: `Please summarize this conversation history:\n\n${contentToSummarize}`,
+                        },
+                    ],
+                    maxTokens: 1000,
+                    _skipCompaction: true, // Prevent recursive compaction during summary generation
+                });
+                summary = summaryResult.status === "complete" ? summaryResult.text : "";
+                summaryTier = 0;
+                // Try to parse structured summary if enabled
+                if (enableStructuredSummary) {
+                    try {
+                        structuredSummary = JSON.parse(summary);
+                    }
+                    catch {
+                        // If parsing fails, keep as plain text
+                    }
+                }
+            }
+        }
+        else if (strategy === "structured" || enableStructuredSummary) {
+            // Structured strategy: generate JSON with sections
+            const contentToSummarize = formatMessagesForSummary(oldMessages);
+            const summaryResult = await agent.generate({
+                messages: [
+                    { role: "system", content: STRUCTURED_SUMMARY_PROMPT },
+                    {
+                        role: "user",
+                        content: `Please summarize this conversation history:\n\n${contentToSummarize}`,
+                    },
+                ],
+                maxTokens: 1000,
+                _skipCompaction: true, // Prevent recursive compaction during summary generation
+            });
+            summary = summaryResult.status === "complete" ? summaryResult.text : "";
+            // Try to parse structured summary
+            try {
+                structuredSummary = JSON.parse(summary);
+            }
+            catch {
+                // If parsing fails, keep as plain text
+            }
+        }
+        else {
+            // Rollup strategy (default): single summary of old messages
+            const contentToSummarize = formatMessagesForSummary(oldMessages);
+            const summaryPrompt = summarizationConfig.summaryPrompt ?? DEFAULT_SUMMARY_PROMPT;
+            const summaryResult = await agent.generate({
+                messages: [
+                    { role: "system", content: summaryPrompt },
+                    {
+                        role: "user",
+                        content: `Please summarize this conversation history:\n\n${contentToSummarize}`,
+                    },
+                ],
+                maxTokens: 1000,
+                _skipCompaction: true, // Prevent recursive compaction during summary generation
+            });
+            summary = summaryResult.status === "complete" ? summaryResult.text : "";
+        }
+        // Build new message history
+        const summaryPrefix = summaryTier !== undefined
+            ? `[Previous conversation summary - Tier ${summaryTier}]`
+            : "[Previous conversation summary]";
+        const summaryMessage = {
+            role: "assistant",
+            content: structuredSummary
+                ? `${summaryPrefix}\n\n${formatStructuredSummary(structuredSummary)}`
+                : `${summaryPrefix}\n\n${summary}`,
+        };
+        const newMessages = [
+            ...systemMessages,
+            summaryMessage,
+            ...pinnedMessagesArray, // Include pinned messages
+            ...recentMessages,
+        ];
+        const tokensAfter = tokenCounter.countMessages(newMessages);
+        const result = {
+            messagesBefore,
+            messagesAfter: newMessages.length,
+            tokensBefore,
+            tokensAfter,
+            summary,
+            compactedMessages: oldMessages,
+            newMessages,
+            trigger,
+            strategy,
+            structuredSummary,
+            summaryTier,
+        };
+        onCompact?.(result);
+        return result;
+    };
+    const process = async (messages, agent) => {
+        const { trigger, reason } = shouldCompact(messages);
+        if (trigger && reason) {
+            // If background compaction is enabled and scheduler exists
+            if (scheduler && options.scheduler?.enableBackgroundCompaction) {
+                // Check if there's a pending result from a previous background compaction
+                const latestResult = scheduler.getLatestResult();
+                if (latestResult) {
+                    // Apply the background compaction result
+                    scheduler.cleanup(); // Clean up old completed tasks
+                    return latestResult.newMessages;
+                }
+                // Schedule a new background compaction for next time
+                scheduler.schedule(messages, agent, reason);
+                // Return original messages (compaction will happen in background)
+                return messages;
+            }
+            else {
+                // Synchronous compaction (blocking)
+                const result = await compact(messages, agent, reason);
+                return result.newMessages;
+            }
+        }
+        return messages;
+    };
+    const updateUsage = (usage) => {
+        // Store actual usage for next budget calculation
+        // Only store if totalTokens is defined
+        if (usage.totalTokens !== undefined) {
+            lastActualUsage = {
+                inputTokens: usage.inputTokens,
+                totalTokens: usage.totalTokens,
+            };
+        }
+    };
+    const pinMessage = (messageIndex, reason) => {
+        // Check if already pinned
+        if (pinnedMessages.some((p) => p.messageIndex === messageIndex)) {
+            return;
+        }
+        pinnedMessages.push({
+            messageIndex,
+            reason,
+            pinnedAt: Date.now(),
+        });
+    };
+    const unpinMessage = (messageIndex) => {
+        const index = pinnedMessages.findIndex((p) => p.messageIndex === messageIndex);
+        if (index !== -1) {
+            pinnedMessages.splice(index, 1);
+        }
+    };
+    const isPinned = (messageIndex) => {
+        return pinnedMessages.some((p) => p.messageIndex === messageIndex);
+    };
+    // Create the manager object (needed for scheduler creation)
+    const manager = {
+        tokenCounter,
+        policy,
+        summarizationConfig,
+        maxTokens,
+        scheduler: undefined, // Will be set below if needed
+        pinnedMessages,
+        getBudget,
+        shouldCompact,
+        compact,
+        process,
+        updateUsage,
+        pinMessage,
+        unpinMessage,
+        isPinned,
+    };
+    // Create scheduler after manager is defined (to pass to createCompactionScheduler)
+    if (options.scheduler?.enableBackgroundCompaction) {
+        scheduler = createCompactionScheduler(manager, options.scheduler);
+        manager.scheduler = scheduler;
+    }
+    return manager;
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Formats messages into a string suitable for summarization.
+ *
+ * @param messages - Messages to format
+ * @returns Formatted string representation
+ */
+/**
+ * Helper function to extract metadata from image parts for summarization.
+ */
+function extractImageMetadata(part) {
+    const image = part.image;
+    // Handle URL case
+    if (typeof image === "object" && image !== null && "toString" in image) {
+        const url = image.toString();
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            return `[Image: ${url}]`;
+        }
+    }
+    // Handle data content case (base64, Buffer, etc.)
+    if (typeof image === "string") {
+        // Check if it's a data URL
+        if (image.startsWith("data:")) {
+            const mimeMatch = image.match(/^data:([^;,]+)/);
+            const mimeType = mimeMatch ? mimeMatch[1] : "unknown";
+            return `[Image: ${mimeType}, base64 data]`;
+        }
+    }
+    return "[Image: embedded data]";
+}
+/**
+ * Helper function to extract metadata from file parts for summarization.
+ */
+function extractFileMetadata(part) {
+    const mimeType = part.mimeType ?? "unknown";
+    // Handle URL case
+    const data = part.data;
+    if (typeof data === "object" && data !== null && "toString" in data) {
+        const url = data.toString();
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            return `[File: ${mimeType}, URL: ${url}]`;
+        }
+    }
+    // Handle data content case
+    return `[File: ${mimeType}, embedded data]`;
+}
+function formatMessagesForSummary(messages) {
+    const lines = [];
+    for (const message of messages) {
+        const role = message.role.toUpperCase();
+        if (typeof message.content === "string") {
+            lines.push(`${role}: ${message.content}`);
+        }
+        else if (Array.isArray(message.content)) {
+            const parts = [];
+            for (const part of message.content) {
+                if ("text" in part && typeof part.text === "string") {
+                    parts.push(part.text);
+                }
+                else if ("toolName" in part) {
+                    parts.push(`[Tool call: ${part.toolName}]`);
+                }
+                else if ("result" in part || "output" in part) {
+                    const output = "result" in part ? part.result : part.output;
+                    const outputStr = typeof output === "string"
+                        ? output.slice(0, 200)
+                        : JSON.stringify(output).slice(0, 200);
+                    parts.push(`[Tool result: ${outputStr}...]`);
+                }
+                else if ("image" in part && part.type === "image") {
+                    parts.push(extractImageMetadata(part));
+                }
+                else if ("data" in part && part.type === "file") {
+                    parts.push(extractFileMetadata(part));
+                }
+            }
+            if (parts.length > 0) {
+                lines.push(`${role}: ${parts.join("\n")}`);
+            }
+        }
+    }
+    return lines.join("\n\n");
+}
+/**
+ * Extracts tool results from messages.
+ *
+ * @param messages - Messages to search
+ * @returns Array of tool results with their context
+ */
+export function extractToolResults(messages) {
+    const results = [];
+    messages.forEach((message, index) => {
+        if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if ("result" in part || "output" in part) {
+                    results.push({
+                        toolName: "toolName" in part ? String(part.toolName) : "unknown",
+                        output: "result" in part ? part.result : part.output,
+                        messageIndex: index,
+                    });
+                }
+            }
+        }
+    });
+    return results;
+}
+/**
+ * Finds the last user message in the conversation.
+ *
+ * @param messages - Messages to search
+ * @returns The last user message content, or undefined
+ */
+export function findLastUserMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (!message)
+            continue;
+        if (message.role === "user") {
+            if (typeof message.content === "string") {
+                return message.content;
+            }
+            else if (Array.isArray(message.content)) {
+                for (const part of message.content) {
+                    if ("text" in part && typeof part.text === "string") {
+                        return part.text;
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Counts messages by role.
+ *
+ * @param messages - Messages to count
+ * @returns Object with counts per role
+ */
+export function countMessagesByRole(messages) {
+    const counts = {};
+    for (const message of messages) {
+        counts[message.role] = (counts[message.role] ?? 0) + 1;
+    }
+    return counts;
+}
+/**
+ * Formats a structured summary into a readable markdown string.
+ *
+ * @param summary - Structured summary to format
+ * @returns Formatted markdown string
+ */
+function formatStructuredSummary(summary) {
+    const sections = [];
+    if (summary.decisions.length > 0) {
+        sections.push(`## Decisions\n${summary.decisions.map((d) => `- ${d}`).join("\n")}`);
+    }
+    if (summary.preferences.length > 0) {
+        sections.push(`## Preferences\n${summary.preferences.map((p) => `- ${p}`).join("\n")}`);
+    }
+    if (summary.currentState.length > 0) {
+        sections.push(`## Current State\n${summary.currentState.map((s) => `- ${s}`).join("\n")}`);
+    }
+    if (summary.openQuestions.length > 0) {
+        sections.push(`## Open Questions\n${summary.openQuestions.map((q) => `- ${q}`).join("\n")}`);
+    }
+    if (summary.references.length > 0) {
+        sections.push(`## References\n${summary.references.map((r) => `- ${r}`).join("\n")}`);
+    }
+    return sections.join("\n\n");
+}
+//# sourceMappingURL=context-manager.js.map