@juspay/neurolink 9.5.2 → 9.6.0

package/dist/context/fileSummarizationService.js

@@ -0,0 +1,255 @@
+/**
+ * File Summarization Service
+ *
+ * Orchestrates the end-to-end file summarization pipeline:
+ *  1. Accept raw file inputs (strings or Buffers)
+ *  2. Extract readable text and estimate tokens
+ *  3. Use `planFileSummarization()` to decide which files to summarize
+ *  4. Call an LLM to produce context-aware summaries of the largest files
+ *  5. Fall back to truncation when the LLM call fails
+ *
+ * The LLM is instantiated via a *dynamic import* of NeuroLink to avoid
+ * circular dependency issues (NeuroLink → fileSummarizationService → NeuroLink).
+ */
+import { estimateTokens } from "../utils/tokenEstimation.js";
+import { buildFileSummarizationPrompt, planFileSummarization, } from "./fileSummarizer.js";
+// ---------------------------------------------------------------------------
+// MIME → human label mapping
+// ---------------------------------------------------------------------------
+const MIME_LABEL_MAP = {
+    "application/pdf": "PDF Document",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "Word Document",
+    "application/msword": "Word Document",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "Excel Spreadsheet",
+    "application/vnd.ms-excel": "Excel Spreadsheet",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "PowerPoint Presentation",
+    "application/vnd.ms-powerpoint": "PowerPoint Presentation",
+    "application/json": "JSON File",
+    "application/xml": "XML File",
+    "text/xml": "XML File",
+    "text/html": "HTML Document",
+    "text/css": "CSS Stylesheet",
+    "text/csv": "CSV File",
+    "text/plain": "Text File",
+    "text/markdown": "Markdown Document",
+    "application/javascript": "JavaScript File",
+    "text/javascript": "JavaScript File",
+    "application/typescript": "TypeScript File",
+    "text/typescript": "TypeScript File",
+    "application/yaml": "YAML File",
+    "text/yaml": "YAML File",
+    "image/svg+xml": "SVG Image",
+    "application/rtf": "RTF Document",
+    "text/rtf": "RTF Document",
+    "application/zip": "ZIP Archive",
+    "application/gzip": "GZip Archive",
+};
+/** Binary MIME type prefixes that cannot be meaningfully extracted as text. */
+const BINARY_MIME_PREFIXES = ["image/", "audio/", "video/"];
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+export class FileSummarizationService {
+    provider;
+    model;
+    constructor(options) {
+        this.provider = options?.provider ?? "vertex";
+        this.model = options?.model ?? "gemini-2.5-flash";
+    }
+    // -------------------------------------------------------------------------
+    // Text extraction
+    // -------------------------------------------------------------------------
+    /**
+     * Extract readable text from a file's content.
+     *
+     * - Strings are returned as-is.
+     * - Buffers are decoded as UTF-8 when the MIME type is textual.
+     * - Known-binary types (image/*, audio/*, video/*) return a placeholder.
+     */
+    extractFileText(content, mimeType, fileName) {
+        // String content — already text
+        if (typeof content === "string") {
+            return content;
+        }
+        // Binary MIME types → placeholder
+        const isBinary = BINARY_MIME_PREFIXES.some((prefix) => mimeType.startsWith(prefix));
+        if (isBinary) {
+            return `[Binary file: ${fileName} (${mimeType}, ${content.length} bytes)]`;
+        }
+        // Buffer with text-like MIME → decode as UTF-8
+        try {
+            return content.toString("utf-8");
+        }
+        catch {
+            return `[Binary file: ${fileName} (${mimeType}, ${content.length} bytes)]`;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // MIME → label
+    // -------------------------------------------------------------------------
+    /**
+     * Map a MIME type (and filename for fallback) to a human-readable label.
+     */
+    getFileTypeLabel(mimeType, fileName) {
+        // Direct lookup
+        if (MIME_LABEL_MAP[mimeType]) {
+            return MIME_LABEL_MAP[mimeType];
+        }
+        // Extension-based fallback
+        const ext = fileName.split(".").pop()?.toLowerCase();
+        switch (ext) {
+            case "ts":
+            case "tsx":
+                return "TypeScript File";
+            case "js":
+            case "jsx":
+                return "JavaScript File";
+            case "py":
+                return "Python File";
+            case "java":
+                return "Java File";
+            case "go":
+                return "Go File";
+            case "rs":
+                return "Rust File";
+            case "rb":
+                return "Ruby File";
+            case "php":
+                return "PHP File";
+            case "c":
+            case "h":
+                return "C File";
+            case "cpp":
+            case "hpp":
+            case "cc":
+                return "C++ File";
+            case "cs":
+                return "C# File";
+            case "swift":
+                return "Swift File";
+            case "kt":
+                return "Kotlin File";
+            case "md":
+                return "Markdown Document";
+            case "yaml":
+            case "yml":
+                return "YAML File";
+            case "toml":
+                return "TOML File";
+            case "ini":
+            case "cfg":
+                return "Config File";
+            case "sh":
+            case "bash":
+                return "Shell Script";
+            case "sql":
+                return "SQL File";
+            case "csv":
+                return "CSV File";
+            case "json":
+                return "JSON File";
+            case "xml":
+                return "XML File";
+            case "html":
+            case "htm":
+                return "HTML Document";
+            default:
+                return "File";
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Preparation
+    // -------------------------------------------------------------------------
+    /**
+     * Convert an array of raw file inputs into `FileForSummarization` objects.
+     *
+     * Extracts text and estimates token count for each file.
+     */
+    prepareFilesForSummarization(files, provider) {
+        const effectiveProvider = provider ?? this.provider;
+        return files.map((file) => {
+            const text = this.extractFileText(file.content, file.mimeType, file.fileName);
+            const estimatedTokens = estimateTokens(text, effectiveProvider);
+            const fileType = this.getFileTypeLabel(file.mimeType, file.fileName);
+            return {
+                fileName: file.fileName,
+                fileType,
+                content: text,
+                estimatedTokens,
+                mimeType: file.mimeType,
+                originalSize: file.originalSize,
+            };
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Summarization
+    // -------------------------------------------------------------------------
+    /**
+     * Summarize files that exceed the context budget.
+     *
+     * For each file marked "summarize" by `planFileSummarization()`, we call
+     * the configured LLM to produce a context-aware summary. If the LLM call
+     * fails, we fall back to naive truncation so the request can still proceed.
+     */
+    async summarizeFiles(files, userPrompt, budgetParams) {
+        const plan = planFileSummarization(files, budgetParams);
+        const results = [];
+        for (const entry of plan) {
+            if (entry.action === "keep") {
+                results.push({
+                    fileName: entry.file.fileName,
+                    fileType: entry.file.fileType,
+                    summary: entry.file.content,
+                    originalTokens: entry.file.estimatedTokens,
+                    summaryTokens: entry.file.estimatedTokens,
+                    wasSummarized: false,
+                });
+                continue;
+            }
+            // Action is "summarize"
+            const targetTokens = entry.targetTokens ?? 2000;
+            try {
+                // Dynamic import to avoid circular dependency
+                const { NeuroLink } = await import("../neurolink.js");
+                const summarizer = new NeuroLink();
+                const prompt = buildFileSummarizationPrompt({
+                    fileName: entry.file.fileName,
+                    fileType: entry.file.fileType,
+                    fileContent: entry.file.content,
+                    userPrompt,
+                    targetTokens,
+                });
+                const result = await summarizer.generate({
+                    input: { text: prompt },
+                    provider: this.provider,
+                    model: this.model,
+                });
+                const summaryText = typeof result === "string" ? result : (result?.content ?? "");
+                const summaryTokens = estimateTokens(summaryText, budgetParams.provider);
+                results.push({
+                    fileName: entry.file.fileName,
+                    fileType: entry.file.fileType,
+                    summary: summaryText,
+                    originalTokens: entry.file.estimatedTokens,
+                    summaryTokens,
+                    wasSummarized: true,
+                });
+            }
+            catch {
+                // Fallback: naive truncation
+                const { truncateToTokenBudget } = await import("../utils/tokenEstimation.js");
+                const { text: truncated } = truncateToTokenBudget(entry.file.content, targetTokens, budgetParams.provider);
+                const summaryTokens = estimateTokens(truncated, budgetParams.provider);
+                results.push({
+                    fileName: entry.file.fileName,
+                    fileType: entry.file.fileType,
+                    summary: truncated,
+                    originalTokens: entry.file.estimatedTokens,
+                    summaryTokens,
+                    wasSummarized: true,
+                });
+            }
+        }
+        return results;
+    }
+}

package/dist/context/fileSummarizer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * File Content Summarization Pipeline
+ *
+ * Provides utilities to detect when attached file content exceeds the
+ * model's available context budget and to plan / build prompts for
+ * LLM-driven summarization of the largest files.
+ *
+ * Design rationale:
+ *  - Files are the #1 cause of context overflow when users attach
+ *    multiple large documents (PDFs, spreadsheets, source code).
+ *  - Rather than blindly truncating, we ask an LLM to produce a
+ *    *context-aware* summary that retains the information most
+ *    relevant to the user's actual question.
+ *  - The caller (FileSummarizationService) is responsible for the
+ *    actual LLM calls; this module is pure computation + types.
+ */
+import type { FileForSummarization, FileSummarizationCheckParams, FileSummarizationCheckResult, FileSummarizationPromptParams, FileSummarizationPlanEntry } from "../types/contextTypes.js";
+export type { FileForSummarization, FileSummarizationCheckParams, FileSummarizationCheckResult, FileSummarizationPromptParams, SummarizedFile, FileSummarizationPlanEntry, } from "../types/contextTypes.js";
+/** Fraction of the context window reserved for non-file content overhead */
+export declare const NON_FILE_RESERVE = 0.15;
+/** Minimum tokens a single file can be allocated in the plan */
+export declare const MIN_PER_FILE_TOKENS = 500;
+/** Maximum tokens a single file can be allocated in the plan */
+export declare const MAX_PER_FILE_TOKENS = 4000;
+/**
+ * Files with fewer estimated tokens than this threshold are never
+ * summarized — they're already small enough to include verbatim.
+ */
+export declare const FILE_SUMMARIZATION_THRESHOLD = 1000;
+/**
+ * Check whether the attached files push the total input token count
+ * beyond the model's available context window.
+ *
+ * When the total exceeds the budget, we calculate how many tokens are
+ * available for files (after accounting for system prompt, conversation
+ * history, current prompt, and tool definitions) and divide that
+ * equally across all files to derive a per-file budget.
+ */
+export declare function shouldSummarizeFiles(params: FileSummarizationCheckParams): FileSummarizationCheckResult;
+/**
+ * Build the LLM prompt used to summarize a single file's content.
+ *
+ * The prompt is *context-aware*: it includes the user's original question
+ * so the LLM can prioritise the most relevant parts of the file.
+ */
+export declare function buildFileSummarizationPrompt(params: FileSummarizationPromptParams): string;
+/**
+ * Decide which files need summarization and how much budget each gets.
+ *
+ * Strategy:
+ *  1. Sort files largest-first.
+ *  2. Walk through the list, marking the largest files for summarization
+ *     until the cumulative saved tokens bring us under budget.
+ *  3. Files below `FILE_SUMMARIZATION_THRESHOLD` are never summarized.
+ */
+export declare function planFileSummarization(files: FileForSummarization[], params: FileSummarizationCheckParams): FileSummarizationPlanEntry[];

package/dist/context/fileSummarizer.js

@@ -0,0 +1,145 @@
+/**
+ * File Content Summarization Pipeline
+ *
+ * Provides utilities to detect when attached file content exceeds the
+ * model's available context budget and to plan / build prompts for
+ * LLM-driven summarization of the largest files.
+ *
+ * Design rationale:
+ *  - Files are the #1 cause of context overflow when users attach
+ *    multiple large documents (PDFs, spreadsheets, source code).
+ *  - Rather than blindly truncating, we ask an LLM to produce a
+ *    *context-aware* summary that retains the information most
+ *    relevant to the user's actual question.
+ *  - The caller (FileSummarizationService) is responsible for the
+ *    actual LLM calls; this module is pure computation + types.
+ */
+import { getAvailableInputTokens } from "../constants/contextWindows.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Fraction of the context window reserved for non-file content overhead */
+export const NON_FILE_RESERVE = 0.15;
+/** Minimum tokens a single file can be allocated in the plan */
+export const MIN_PER_FILE_TOKENS = 500;
+/** Maximum tokens a single file can be allocated in the plan */
+export const MAX_PER_FILE_TOKENS = 4000;
+/**
+ * Files with fewer estimated tokens than this threshold are never
+ * summarized — they're already small enough to include verbatim.
+ */
+export const FILE_SUMMARIZATION_THRESHOLD = 1000;
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+/**
+ * Check whether the attached files push the total input token count
+ * beyond the model's available context window.
+ *
+ * When the total exceeds the budget, we calculate how many tokens are
+ * available for files (after accounting for system prompt, conversation
+ * history, current prompt, and tool definitions) and divide that
+ * equally across all files to derive a per-file budget.
+ */
+export function shouldSummarizeFiles(params) {
+    const { provider, model, systemPromptTokens, conversationHistoryTokens, currentPromptTokens, toolDefinitionTokens, fileTokens, fileCount = 1, maxTokens, threshold = 0.8, minTokensPerFile = MIN_PER_FILE_TOKENS, maxTokensPerFile = MAX_PER_FILE_TOKENS, } = params;
+    const availableInputTokens = getAvailableInputTokens(provider, model, maxTokens);
+    const nonFileTokens = systemPromptTokens +
+        conversationHistoryTokens +
+        currentPromptTokens +
+        toolDefinitionTokens;
+    const totalEstimatedTokens = nonFileTokens + fileTokens;
+    // Budget for files = available input minus non-file content minus a reserve
+    const reserveTokens = Math.ceil(availableInputTokens * NON_FILE_RESERVE);
+    const availableBudgetForFiles = Math.max(0, availableInputTokens - nonFileTokens - reserveTokens);
+    const usageRatio = availableInputTokens > 0 ? totalEstimatedTokens / availableInputTokens : 1;
+    const needsSummarization = usageRatio >= threshold || fileTokens > availableBudgetForFiles;
+    let perFileBudget;
+    if (needsSummarization && fileCount > 0) {
+        const rawBudget = Math.floor(availableBudgetForFiles / fileCount);
+        perFileBudget = Math.max(minTokensPerFile, Math.min(maxTokensPerFile, rawBudget));
+    }
+    return {
+        needsSummarization,
+        totalEstimatedTokens,
+        availableInputTokens,
+        availableBudgetForFiles,
+        perFileBudget,
+    };
+}
+/**
+ * Build the LLM prompt used to summarize a single file's content.
+ *
+ * The prompt is *context-aware*: it includes the user's original question
+ * so the LLM can prioritise the most relevant parts of the file.
+ */
+export function buildFileSummarizationPrompt(params) {
+    const { fileName, fileType, fileContent, userPrompt, targetTokens } = params;
+    return [
+        `You are a document summarization assistant. Your task is to summarize the following ${fileType} file in a way that preserves the most important information relevant to the user's question.`,
+        ``,
+        `## User's Question`,
+        `${userPrompt}`,
+        ``,
+        `## File: ${fileName} (${fileType})`,
+        ``,
+        `${fileContent}`,
+        ``,
+        `## Instructions`,
+        `1. Produce a concise summary of the file content above.`,
+        `2. Focus on information that is most relevant to the user's question.`,
+        `3. Preserve key data points, names, numbers, and relationships.`,
+        `4. Target approximately ${targetTokens} tokens in your summary.`,
+        `5. If the file contains structured data (tables, lists), preserve the structure in a compact form.`,
+        `6. Start your summary directly — do not include preamble like "Here is a summary".`,
+    ].join("\n");
+}
+/**
+ * Decide which files need summarization and how much budget each gets.
+ *
+ * Strategy:
+ *  1. Sort files largest-first.
+ *  2. Walk through the list, marking the largest files for summarization
+ *     until the cumulative saved tokens bring us under budget.
+ *  3. Files below `FILE_SUMMARIZATION_THRESHOLD` are never summarized.
+ */
+export function planFileSummarization(files, params) {
+    const checkResult = shouldSummarizeFiles({
+        ...params,
+        fileCount: files.length,
+    });
+    // If no summarization needed, keep everything
+    if (!checkResult.needsSummarization) {
+        return files.map((file) => ({ file, action: "keep" }));
+    }
+    // Sort largest first (descending by estimatedTokens)
+    const sorted = [...files].sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+    const perFileBudget = checkResult.perFileBudget ?? MAX_PER_FILE_TOKENS;
+    // Calculate how many tokens we need to save
+    const totalFileTokens = files.reduce((sum, f) => sum + f.estimatedTokens, 0);
+    const tokensToSave = Math.max(0, totalFileTokens - checkResult.availableBudgetForFiles);
+    let savedSoFar = 0;
+    const plan = [];
+    for (const file of sorted) {
+        // Never summarize tiny files
+        if (file.estimatedTokens < FILE_SUMMARIZATION_THRESHOLD ||
+            savedSoFar >= tokensToSave) {
+            plan.push({ file, action: "keep" });
+        }
+        else {
+            const savingsFromThisFile = file.estimatedTokens - perFileBudget;
+            if (savingsFromThisFile > 0) {
+                plan.push({
+                    file,
+                    action: "summarize",
+                    targetTokens: perFileBudget,
+                });
+                savedSoFar += savingsFromThisFile;
+            }
+            else {
+                plan.push({ file, action: "keep" });
+            }
+        }
+    }
+    return plan;
+}

package/dist/context/fileTokenBudget.d.ts

@@ -0,0 +1,53 @@
+/**
+ * File Token Budget System
+ *
+ * Calculates how much of the remaining context window budget
+ * can be used for file reads. Implements fast-path for small files
+ * and preview mode for very large files.
+ */
+import type { BudgetFileInput } from "../types/contextTypes.js";
+export type { BudgetFileInput } from "../types/contextTypes.js";
+/** Percentage of remaining context to allocate for file reads */
+export declare const FILE_READ_BUDGET_PERCENT = 0.6;
+/** Files below this size skip budget validation (100KB) */
+export declare const FILE_FAST_PATH_SIZE: number;
+/** Files above this size get preview-only mode (5MB) */
+export declare const FILE_PREVIEW_MODE_SIZE: number;
+/** Default preview size in characters */
+export declare const FILE_PREVIEW_CHARS = 2000;
+/**
+ * Calculate available token budget for file reads.
+ *
+ * @param contextWindow - Total context window for the model
+ * @param currentTokens - Tokens already used (conversation + system prompt)
+ * @param maxOutputTokens - Reserved output tokens
+ * @returns Available tokens for file content
+ */
+export declare function calculateFileTokenBudget(contextWindow: number, currentTokens: number, maxOutputTokens: number): number;
+/**
+ * Determine how a file should be handled based on its size and the budget.
+ */
+export declare function shouldTruncateFile(fileSize: number, budget: number): {
+    shouldTruncate: boolean;
+    maxChars?: number;
+    previewMode?: boolean;
+};
+/**
+ * Estimate post-processing token count based on file type.
+ *
+ * Different file types produce vastly different amounts of text after
+ * processing.  A 50 MB video file yields ~200-500 tokens of metadata,
+ * while a 50 MB text file yields ~12.5 M tokens.  Using the raw byte
+ * size for all types causes media files to be wrongly excluded by the
+ * aggregate budget check.
+ *
+ * @param sizeBytes  Raw file size in bytes
+ * @param fileType   Detected file type (e.g. "video", "audio", "image")
+ * @returns Estimated token count after processing
+ */
+export declare function estimatePostProcessingTokens(sizeBytes: number, fileType?: string): number;
+export declare function enforceAggregateFileBudget(files: BudgetFileInput[], availableTokens: number): {
+    included: BudgetFileInput[];
+    excluded: BudgetFileInput[];
+    notices: string[];
+};

package/dist/context/fileTokenBudget.js

@@ -0,0 +1,127 @@
+/**
+ * File Token Budget System
+ *
+ * Calculates how much of the remaining context window budget
+ * can be used for file reads. Implements fast-path for small files
+ * and preview mode for very large files.
+ */
+/** Percentage of remaining context to allocate for file reads */
+export const FILE_READ_BUDGET_PERCENT = 0.6;
+/** Files below this size skip budget validation (100KB) */
+export const FILE_FAST_PATH_SIZE = 100 * 1024;
+/** Files above this size get preview-only mode (5MB) */
+export const FILE_PREVIEW_MODE_SIZE = 5 * 1024 * 1024;
+/** Default preview size in characters */
+export const FILE_PREVIEW_CHARS = 2000;
+/**
+ * Calculate available token budget for file reads.
+ *
+ * @param contextWindow - Total context window for the model
+ * @param currentTokens - Tokens already used (conversation + system prompt)
+ * @param maxOutputTokens - Reserved output tokens
+ * @returns Available tokens for file content
+ */
+export function calculateFileTokenBudget(contextWindow, currentTokens, maxOutputTokens) {
+    const remainingTokens = contextWindow - currentTokens - maxOutputTokens;
+    if (remainingTokens <= 0) {
+        return 0;
+    }
+    return Math.floor(remainingTokens * FILE_READ_BUDGET_PERCENT);
+}
+/**
+ * Determine how a file should be handled based on its size and the budget.
+ */
+export function shouldTruncateFile(fileSize, budget) {
+    // Very large files: preview mode
+    if (fileSize > FILE_PREVIEW_MODE_SIZE) {
+        return {
+            shouldTruncate: true,
+            maxChars: FILE_PREVIEW_CHARS,
+            previewMode: true,
+        };
+    }
+    // Small files: skip validation
+    if (fileSize < FILE_FAST_PATH_SIZE) {
+        return { shouldTruncate: false };
+    }
+    // Estimate tokens (4 chars per token, rough)
+    const estimatedTokens = Math.ceil(fileSize / 4);
+    if (estimatedTokens <= budget) {
+        return { shouldTruncate: false };
+    }
+    // Truncate to fit budget
+    const maxChars = budget * 4; // Convert back to chars
+    return {
+        shouldTruncate: true,
+        maxChars: Math.max(FILE_PREVIEW_CHARS, maxChars),
+        previewMode: false,
+    };
+}
+/**
+ * Estimate post-processing token count based on file type.
+ *
+ * Different file types produce vastly different amounts of text after
+ * processing.  A 50 MB video file yields ~200-500 tokens of metadata,
+ * while a 50 MB text file yields ~12.5 M tokens.  Using the raw byte
+ * size for all types causes media files to be wrongly excluded by the
+ * aggregate budget check.
+ *
+ * @param sizeBytes  Raw file size in bytes
+ * @param fileType   Detected file type (e.g. "video", "audio", "image")
+ * @returns Estimated token count after processing
+ */
+export function estimatePostProcessingTokens(sizeBytes, fileType) {
+    switch (fileType) {
+        // Media files produce only metadata text (~100-500 tokens)
+        case "video":
+            return 500;
+        case "audio":
+            return 300;
+        // Images are sent as base64 — provider counts them as ~1500 tokens each
+        case "image":
+            return 1500;
+        // Archives produce a file listing (~500-2000 tokens)
+        case "archive":
+            return 1000;
+        // Unknown binary files produce metadata + extracted strings (~200-1000 tokens)
+        case "unknown":
+            return 500;
+        // PDFs are sent natively on some providers; estimate ~1 token per 100 bytes, capped
+        case "pdf":
+            return Math.min(Math.ceil(sizeBytes / 100), 50_000);
+        // Structured documents (Excel, Word, PPTX) extract text — roughly 15% of raw size
+        case "xlsx":
+        case "docx":
+        case "pptx":
+            return Math.ceil((sizeBytes * 0.15) / 4);
+        // SVG is sanitized markup — usually small
+        case "svg":
+            return Math.ceil(sizeBytes / 4);
+        // CSV, text, code — raw text roughly 1 token per 4 bytes
+        case "csv":
+        case "text":
+        default:
+            // Original formula: base64-inflate then divide by 4
+            return Math.ceil((sizeBytes * 1.33) / 4);
+    }
+}
+export function enforceAggregateFileBudget(files, availableTokens) {
+    const TOKEN_BUDGET_FOR_FILES = Math.floor(availableTokens * FILE_READ_BUDGET_PERCENT);
+    let usedTokens = 0;
+    const included = [];
+    const excluded = [];
+    const notices = [];
+    const sorted = [...files].sort((a, b) => a.sizeBytes - b.sizeBytes);
+    for (const file of sorted) {
+        const estimatedTokens = estimatePostProcessingTokens(file.sizeBytes, file.fileType);
+        if (usedTokens + estimatedTokens <= TOKEN_BUDGET_FOR_FILES) {
+            usedTokens += estimatedTokens;
+            included.push(file);
+        }
+        else {
+            excluded.push(file);
+            notices.push(`Skipped "${file.name}" (${(file.sizeBytes / 1024).toFixed(0)} KB) — exceeds context budget`);
+        }
+    }
+    return { included, excluded, notices };
+}

package/dist/context/prompts/summarizationPrompt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Summarization Prompt Builder
+ *
+ * Builds prompts for summarizing conversation context into a 9-section structure.
+ * Supports both initial summarization and incremental merging with existing summaries.
+ */
+import type { SummarizationPromptOptions } from "../../types/contextTypes.js";
+export type { SummarizationPromptOptions } from "../../types/contextTypes.js";
+declare const NINE_SECTIONS: string[];
+/**
+ * Builds a summarization prompt based on the provided options.
+ *
+ * @param options - Configuration for the prompt builder
+ * @returns The constructed prompt string
+ */
+export declare function buildSummarizationPrompt(options: SummarizationPromptOptions): string;
+export { NINE_SECTIONS };