minovative-mind-cli 2.10.0 → 2.11.2

package/dist/services/agent.js

@@ -35,6 +35,7 @@ import { verifyChangedFiles } from './verificationService.js';
 import { buildContextInjection } from '../utils/contextPrompts.js';
 import { registerContextFiles } from '../utils/fileReadGuard.js';
 import { historyText } from '../utils/historyPrompt.js';
+import { loadUserProfile, formatUserProfileForContext, extractAndSaveUserInsights, } from './userProfileService.js';
 // Submodule Imports
 import { AsyncInputHandler } from './agent/inputHandler.js';
 import { processResponse } from './agent/toolLoop.js';
@@ -207,6 +208,7 @@ export async function startAgentLoop(workspaceRoot, version) {
                         hint: 'Manage external workspaces for cross-project development',
                     },
                     { value: '/config-key', label: '/config-key', hint: 'BYOK — Use your own Google AI Studio API key' },
+                    { value: '/profile', label: '/profile', hint: 'View or manage AI observations and persona side-notes' },
                     { value: '/stats', label: '/stats', hint: 'View current session statistics and configuration' },
                     { value: '/commit', label: '/commit', hint: 'Auto-commit changes with AI message' },
                     { value: '/revert', label: '/revert', hint: 'Undo last change' },
@@ -451,6 +453,17 @@ export async function executeSingleTurn(workspaceRoot, userInput, chat, inputHan
                     collector.recordCompressedContextSize(contextInjection.length);
                 dynamicSystemInstruction += '\n\n' + contextInjection;
             }
+            // Inject global adaptive user persona and learned preferences
+            try {
+                const userProfile = await loadUserProfile();
+                const profileInjection = formatUserProfileForContext(userProfile);
+                if (profileInjection) {
+                    dynamicSystemInstruction += '\n\n' + profileInjection;
+                }
+            }
+            catch (e) {
+                debugLog(`Failed to inject user profile context: ${e}`);
+            }
             // Apply the dynamic prompt updates and tool registrations to the active chat session
             chat.setAgentConfig(dynamicSystemInstruction, config.tools);
             if (getGlobalActiveModel() === GEMINI_MODELS.AUTO) {
@@ -544,11 +557,18 @@ export async function executeSingleTurn(workspaceRoot, userInput, chat, inputHan
                             parts: [{ text: userInput }],
                         }, {
                             role: 'model',
-                            parts: [{ text: handledByOrchestrator }],
+                            parts: [{ text: `[ORCHESTRATOR_EXECUTION]\n${handledByOrchestrator}` }],
                         });
                         // Print the summary text just like single-agent mode
                         console.log(`\n${pc.blue('◆')} ${pc.bold('Minovative Mind')} ${pc.dim(`(Orchestrator)`)}\n`);
                         console.log(renderTerminalMarkdown(handledByOrchestrator));
+                        // Observe user interaction traits and update global user profile before next prompt
+                        try {
+                            await extractAndSaveUserInsights(userInput, handledByOrchestrator, ac.signal);
+                        }
+                        catch (err) {
+                            debugLog(`Background user profile insight extraction failed: ${err}`);
+                        }
                     }
                     // Print Usage Stats
                     const usage = getAndResetTurnUsage();
@@ -670,6 +690,14 @@ export async function executeSingleTurn(workspaceRoot, userInput, chat, inputHan
                 if (cleanFinalText) {
                     console.log(`\n${pc.blue('◆')} ${pc.bold('Minovative Mind')} ${pc.dim(`(${chat.getModel()})`)}\n`);
                     console.log(renderTerminalMarkdown(cleanFinalText));
+                    chat.appendFinalSummary(cleanFinalText);
+                    // Observe user interaction traits and update global user profile before next prompt
+                    try {
+                        await extractAndSaveUserInsights(userInput, cleanFinalText, ac.signal);
+                    }
+                    catch (err) {
+                        debugLog(`Background user profile insight extraction failed: ${err}`);
+                    }
                 }
             }
             if (usage) {
@@ -989,15 +1017,14 @@ async function compressContextFiles(workspaceRoot, contextResult) {
 }
 /**
  * Raw chat history entry count threshold to trigger chat history summarization.
- * 50 entries = 25 conversational user/model turns.
+ * 2 entries = 1 complete conversational user/model turn.
  */
-export const HISTORY_SUMMARIZATION_THRESHOLD = 50;
+export const HISTORY_SUMMARIZATION_THRESHOLD = 2;
 /**
- * Summarizes older chat history entries if the active session's history
- * exceeds {@link HISTORY_SUMMARIZATION_THRESHOLD} entries.
+ * Summarizes chat history entries starting from the first full user/model turn.
  *
- * Preserves the most recent 20 entries (10 turns) intact for conversational continuity,
- * replacing all preceding turns with a single summarized pair in the chat history.
+ * Compresses preceding conversation history into a structured high-density summary pair
+ * in the active session while permanently preserving uncompressed history in fullHistory.
  *
  * @param chat - The active ProxyChatSession instance.
  * @returns A promise resolving to true if history was summarized and updated; false otherwise.
@@ -1008,12 +1035,8 @@ export async function summarizeHistoryIfNeeded(chat, abortSignal) {
         return false;
     }
     try {
-        // Keep the most recent 20 entries (10 full user/model turns) intact
-        const recentCount = 20;
-        const olderHistory = history.slice(0, history.length - recentCount);
-        const recentHistory = history.slice(history.length - recentCount);
-        debugLog(`Summarizing ${olderHistory.length} older chat history entries...`);
-        const summaryText = await summarizeChatHistory(olderHistory, abortSignal);
+        debugLog(`Summarizing ${history.length} chat history entries (Flash-Lite Summarizer triggered after first turn)...`);
+        const summaryText = await summarizeChatHistory(history, abortSignal);
         if (summaryText && summaryText.trim().length > 0) {
             const summaryContent = [
                 {
@@ -1025,8 +1048,8 @@ export async function summarizeHistoryIfNeeded(chat, abortSignal) {
                     parts: [{ text: 'Understood. I have reviewed and absorbed the summary of our preceding conversation.' }],
                 },
             ];
-            chat.loadCompressedHistory([...summaryContent, ...recentHistory]);
-            debugLog(`Chat history compressed successfully from ${history.length} to ${summaryContent.length + recentHistory.length} entries.`);
+            chat.loadCompressedHistory(summaryContent);
+            debugLog(`Chat history compressed successfully from ${history.length} to ${summaryContent.length} entries.`);
             return true;
         }
     }

package/dist/services/ai.d.ts

@@ -22,6 +22,12 @@ export declare class ProxyChatSession {
     loadRawHistory(history: Content[]): void;
     loadCompressedHistory(history: Content[]): void;
     addTurn(userContent: Content, modelContent: Content): void;
+    /**
+     * Appends or merges the final conversational summary text into the active session history.
+     * Ensures that the final response produced by finish_task, PM reconciliation, or final turns
+     * is permanently preserved as a model text response in both working history and full transcript.
+     */
+    appendFinalSummary(text: string): void;
     /**
      * Retrieves the most recent conversation history as a formatted string.
      * Useful for passing conversation context to stateless background agents.
@@ -42,6 +48,19 @@ export declare class ProxyChatSession {
      * conversational context while preventing OOM crashes.
      */
     private pruneHistory;
+    /**
+     * Collapses oversized functionResponse outputs in historical turns (>1 turn old)
+     * while strictly maintaining Gemini functionCall and functionResponse pairing.
+     *
+     * Gemini requires every functionCall in a model turn to have a matching functionResponse
+     * in the immediately following user turn. Deleting parts or entries breaks this invariant and
+     * causes 400 Bad Request errors. This method mutates oversized response outputs in-place
+     * on older turns to drastically conserve context window tokens.
+     *
+     * @param threshold Maximum characters allowed for a historical tool response before collapsing (default: 1500).
+     * @param turnsToKeep Number of recent turns to preserve unpruned (default: 1).
+     */
+    pruneToolOutputHistory(threshold?: number, turnsToKeep?: number): void;
     sendMessage(message: string | Array<{
         functionResponse: {
             name: string;
@@ -98,6 +117,12 @@ export declare function createHistorySummarizerSession(): any;
  * Summarizes an array of Content history entries using Gemini Flash Lite.
  */
 export declare function summarizeChatHistory(history: Content[], abortSignal?: AbortSignal): Promise<string>;
+export declare function createUserProfileExtractorSession(): any;
+/**
+ * Creates a Flash-Lite session with structured output to classify whether a user message
+ * is trivial/low-signal (greetings, confirmations, terminal commands) or contains substantive signal.
+ */
+export declare function createTrivialMessageClassifierSession(): any;
 /**
  * Generates a concise title for a chat session based on the user's first message.
  */

package/dist/services/ai.js

@@ -5,7 +5,7 @@ import { getMetricCollector } from './metrics.js';
 import { getAuthorizedIdToken, checkByokSubscription } from './auth.js';
 import { debugLog } from '../utils/logger.js';
 import { readCache, writeCache } from '../utils/projectStorage.js';
-import { GENERAL_CHAT_INSTRUCTION, PLAN_EXECUTION_INSTRUCTION, PLAN_MODE_INSTRUCTION, CONTEXT_SYSTEM_INSTRUCTION, INTENT_ROUTER_SYSTEM_INSTRUCTION, WEB_SEARCH_SYSTEM_INSTRUCTION, EXECUTION_COMPLEXITY_SYSTEM_INSTRUCTION, INVESTIGATION_COMPLEXITY_SYSTEM_INSTRUCTION, INVESTIGATION_SEMANTIC_SYSTEM_INSTRUCTION, HISTORY_SUMMARIZER_SYSTEM_INSTRUCTION, } from '../utils/systemPrompts.js';
+import { GENERAL_CHAT_INSTRUCTION, PLAN_EXECUTION_INSTRUCTION, PLAN_MODE_INSTRUCTION, CONTEXT_SYSTEM_INSTRUCTION, INTENT_ROUTER_SYSTEM_INSTRUCTION, WEB_SEARCH_SYSTEM_INSTRUCTION, EXECUTION_COMPLEXITY_SYSTEM_INSTRUCTION, INVESTIGATION_COMPLEXITY_SYSTEM_INSTRUCTION, INVESTIGATION_SEMANTIC_SYSTEM_INSTRUCTION, HISTORY_SUMMARIZER_SYSTEM_INSTRUCTION, USER_PROFILE_EXTRACTOR_SYSTEM_INSTRUCTION, TRIVIAL_MESSAGE_CLASSIFIER_SYSTEM_INSTRUCTION, } from '../utils/systemPrompts.js';
 import { workspaceRegistry } from './workspaceRegistry.js';
 import { loadCredentials } from '../utils/credentialStore.js';
 import { ProxyClient } from './proxyClient.js';
@@ -62,6 +62,14 @@ const MAX_HISTORY_ENTRIES = 500;
  * payload stays within sane memory bounds.
  */
 const MAX_PART_TEXT_LENGTH = 60_000;
+const HISTORICAL_TOOL_OUTPUT_THRESHOLD = 1500;
+const COLLAPSED_TOOL_OUTPUT_MARKER = '\n... [Historical tool output collapsed to save context]';
+function collapseHistoricalOutput(val, threshold = HISTORICAL_TOOL_OUTPUT_THRESHOLD) {
+    if (val.length <= threshold || val.includes('[Historical tool output collapsed')) {
+        return val;
+    }
+    return `${val.substring(0, threshold)}${COLLAPSED_TOOL_OUTPUT_MARKER}`;
+}
 function truncatePartText(text) {
     if (text.length <= MAX_PART_TEXT_LENGTH)
         return text;
@@ -117,6 +125,64 @@ export class ProxyChatSession {
         this.fullHistory.push(JSON.parse(JSON.stringify(userContent)));
         this.fullHistory.push(JSON.parse(JSON.stringify(modelContent)));
     }
+    /**
+     * Appends or merges the final conversational summary text into the active session history.
+     * Ensures that the final response produced by finish_task, PM reconciliation, or final turns
+     * is permanently preserved as a model text response in both working history and full transcript.
+     */
+    appendFinalSummary(text) {
+        if (!text || !text.trim())
+            return;
+        const clean = text.replace(/\[TASK_FINISHED\]/g, '').trim();
+        if (!clean)
+            return;
+        // 1. Ensure fullHistory has the model text response
+        if (this.fullHistory.length > 0) {
+            const lastFull = this.fullHistory[this.fullHistory.length - 1];
+            if (lastFull.role === 'model') {
+                const hasText = lastFull.parts?.some((p) => p.text && p.text.trim() === clean);
+                if (!hasText) {
+                    lastFull.parts = lastFull.parts || [];
+                    lastFull.parts.push({ text: clean });
+                }
+            }
+            else {
+                this.fullHistory.push({
+                    role: 'model',
+                    parts: [{ text: clean }],
+                });
+            }
+        }
+        else {
+            this.fullHistory.push({
+                role: 'model',
+                parts: [{ text: clean }],
+            });
+        }
+        // 2. Ensure working history has the model text response
+        if (this.history.length > 0) {
+            const lastHist = this.history[this.history.length - 1];
+            if (lastHist.role === 'model') {
+                const hasText = lastHist.parts?.some((p) => p.text && p.text.trim() === clean);
+                if (!hasText) {
+                    lastHist.parts = lastHist.parts || [];
+                    lastHist.parts.push({ text: clean });
+                }
+            }
+            else {
+                this.history.push({
+                    role: 'model',
+                    parts: [{ text: clean }],
+                });
+            }
+        }
+        else {
+            this.history.push({
+                role: 'model',
+                parts: [{ text: clean }],
+            });
+        }
+    }
     /**
      * Retrieves the most recent conversation history as a formatted string.
      * Useful for passing conversation context to stateless background agents.
@@ -164,6 +230,7 @@ export class ProxyChatSession {
      * conversational context while preventing OOM crashes.
      */
     async pruneHistory() {
+        this.pruneToolOutputHistory();
         if (this.history.length > MAX_HISTORY_ENTRIES) {
             const excess = this.history.length - MAX_HISTORY_ENTRIES;
             const trimCount = excess % 2 === 0 ? excess : excess + 1;
@@ -181,6 +248,46 @@ export class ProxyChatSession {
             }
         }
     }
+    /**
+     * Collapses oversized functionResponse outputs in historical turns (>1 turn old)
+     * while strictly maintaining Gemini functionCall and functionResponse pairing.
+     *
+     * Gemini requires every functionCall in a model turn to have a matching functionResponse
+     * in the immediately following user turn. Deleting parts or entries breaks this invariant and
+     * causes 400 Bad Request errors. This method mutates oversized response outputs in-place
+     * on older turns to drastically conserve context window tokens.
+     *
+     * @param threshold Maximum characters allowed for a historical tool response before collapsing (default: 1500).
+     * @param turnsToKeep Number of recent turns to preserve unpruned (default: 1).
+     */
+    pruneToolOutputHistory(threshold = HISTORICAL_TOOL_OUTPUT_THRESHOLD, turnsToKeep = 1) {
+        // 1 turn = 1 user Content + 1 model Content pair (2 entries)
+        const cutoffIndex = Math.max(0, this.history.length - turnsToKeep * 2);
+        if (cutoffIndex <= 0)
+            return;
+        for (let i = 0; i < cutoffIndex; i++) {
+            const entry = this.history[i];
+            if (entry && entry.role === 'user' && Array.isArray(entry.parts)) {
+                for (const part of entry.parts) {
+                    if (part && typeof part === 'object' && 'functionResponse' in part && part.functionResponse) {
+                        const funcResp = part.functionResponse;
+                        if (funcResp.response && typeof funcResp.response === 'object') {
+                            const respObj = funcResp.response;
+                            if (typeof respObj.output === 'string') {
+                                respObj.output = collapseHistoricalOutput(respObj.output, threshold);
+                            }
+                            if (typeof respObj.error === 'string') {
+                                respObj.error = collapseHistoricalOutput(respObj.error, threshold);
+                            }
+                            if (typeof respObj.result === 'string') {
+                                respObj.result = collapseHistoricalOutput(respObj.result, threshold);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
     async sendMessage(message, additionalText, abortSignal, onChunk) {
         const idToken = await getAuthorizedIdToken();
         if (!idToken) {
@@ -756,6 +863,150 @@ export async function summarizeChatHistory(history, abortSignal) {
         return '';
     }
 }
+// ─── User Profile Extractor Service ────────────────────────────────────
+export function createUserProfileExtractorSession() {
+    // Configured exclusively with FLASH_LITE for lightweight zero-latency profiling
+    const model = GEMINI_MODELS.FLASH_LITE;
+    return new ProxyChatSession(model, USER_PROFILE_EXTRACTOR_SYSTEM_INSTRUCTION, [], // no tools
+    {
+        temperature: 0,
+        responseMimeType: 'application/json',
+        responseSchema: {
+            type: SchemaType.OBJECT,
+            properties: {
+                tonePreference: {
+                    type: SchemaType.STRING,
+                    description: 'Observed tone and demeanor traits of the user',
+                },
+                verbosity: {
+                    type: SchemaType.STRING,
+                    description: 'Observed verbosity and output formatting preference',
+                },
+                formulationStyle: {
+                    type: SchemaType.STRING,
+                    description: 'Observed thought formulation and prompting style',
+                },
+                cognitiveTraits: {
+                    type: SchemaType.OBJECT,
+                    properties: {
+                        architecturalStyle: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "top-down-design", "bottom-up-code", "balanced"',
+                        },
+                        decisionPreference: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "direct-recommendation", "present-options"',
+                        },
+                        riskTolerance: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "defensive-rigor", "pragmatic-speed"',
+                        },
+                        delegationDepth: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "autonomous-delegation", "hands-on-stepwise"',
+                        },
+                        debuggingStyle: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "minimal-diff-fix", "root-cause-deep-dive"',
+                        },
+                        explanationFormat: {
+                            type: SchemaType.STRING,
+                            description: 'e.g., "code-first", "bullet-summaries", "conceptual-analogies"',
+                        },
+                    },
+                    description: 'Observed cognitive decision-making, collaboration, and problem-solving traits',
+                },
+                strengths: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.STRING,
+                    },
+                    description: 'Observed technical strengths or technologies the user is actively familiar with',
+                },
+                removeStrengths: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.STRING,
+                    },
+                    description: 'Outdated or abandoned technologies to remove when a pivot/contradiction occurs',
+                },
+                conventions: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.STRING,
+                    },
+                    description: 'Observed architectural habits or coding conventions',
+                },
+                removeConventions: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.STRING,
+                    },
+                    description: 'Outdated coding conventions to remove when a pivot/contradiction occurs',
+                },
+                addNotes: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.STRING,
+                    },
+                    description: 'New non-conflicting side-notes to add (empty if none)',
+                },
+                updateNotes: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.OBJECT,
+                        properties: {
+                            index: {
+                                type: SchemaType.INTEGER,
+                                description: '0-based index of the existing note to update',
+                            },
+                            updatedText: {
+                                type: SchemaType.STRING,
+                                description: 'Revised note text that supersedes the outdated observation',
+                            },
+                        },
+                        required: ['index', 'updatedText'],
+                    },
+                    description: 'Targeted updates to existing notes that evolved',
+                },
+                deleteNoteIndices: {
+                    type: SchemaType.ARRAY,
+                    items: {
+                        type: SchemaType.INTEGER,
+                    },
+                    description: '0-based indices of contradicted or obsolete notes to delete',
+                },
+            },
+            required: ['addNotes', 'updateNotes', 'deleteNoteIndices'],
+        },
+    });
+}
+/**
+ * Creates a Flash-Lite session with structured output to classify whether a user message
+ * is trivial/low-signal (greetings, confirmations, terminal commands) or contains substantive signal.
+ */
+export function createTrivialMessageClassifierSession() {
+    const model = GEMINI_MODELS.FLASH_LITE;
+    return new ProxyChatSession(model, TRIVIAL_MESSAGE_CLASSIFIER_SYSTEM_INSTRUCTION, [], // no tools
+    {
+        temperature: 0,
+        responseMimeType: 'application/json',
+        responseSchema: {
+            type: SchemaType.OBJECT,
+            properties: {
+                isTrivial: {
+                    type: SchemaType.BOOLEAN,
+                    description: 'True if the message is a low-signal greeting, confirmation, affirmation, or simple control command with zero technical/personal traits',
+                },
+                reason: {
+                    type: SchemaType.STRING,
+                    description: 'Brief reason for the classification decision',
+                },
+            },
+            required: ['isTrivial'],
+        },
+    });
+}
 /**
  * Generates a concise title for a chat session based on the user's first message.
  */
@@ -773,7 +1024,7 @@ export async function generateChatTitle(firstMessage, abortSignal) {
         const contents = [{ role: 'user', parts: [{ text: firstMessage.substring(0, 500) }] }];
         let model = getGlobalActiveModel();
         if (model === 'auto' || model.includes('claude'))
-            model = GEMINI_MODELS.FLASH;
+            model = GEMINI_MODELS.FLASH_LITE;
         const byokEnabled = await isByokEnabled();
         let result;
         if (byokEnabled) {

package/dist/services/chatHistoryService.d.ts

@@ -1,4 +1,17 @@
 import type { Content } from '@google/generative-ai';
+/**
+ * Options for configuring dynamic history pruning.
+ */
+export interface HistoryPruneOptions {
+    /** Maximum number of history entries (user + model contents) to keep in active memory. Defaults to 50. */
+    maxEntries?: number;
+    /** Maximum estimated tokens allowed for the active conversation history. Defaults to 64,000. */
+    maxTokens?: number;
+    /** Minimum number of recent entries to retain regardless of token limits. Defaults to 10 (5 full turns). */
+    minRecentEntries?: number;
+    /** Whether to automatically archive pruned entries to disk. Defaults to true. */
+    archivePruned?: boolean;
+}
 /**
  * Represents the structure of a saved chat session.
  * This data is persisted in the local workspace cache to allow users to resume
@@ -41,7 +54,16 @@ export interface ChatSessionData {
     modelUsageCounts?: Record<string, number>;
 }
 /**
- * Service responsible for managing the persistence, retrieval, and deletion of chat session histories.
+ * Estimates the token count for a Gemini Content object.
+ *
+ * @param content The Content object containing parts and role.
+ * @returns Estimated number of tokens.
+ */
+export declare function estimateContentTokens(content: Content): number;
+/**
+ * Service responsible for managing the persistence, retrieval, history pruning,
+ * and deletion of chat session histories.
+ *
  * It stores session metadata and message history in a local JSON cache (`chat_sessions.json`)
  * within the project's storage directory and enforces a maximum limit of 250 sessions to prevent
  * unbounded storage growth.
@@ -51,6 +73,10 @@ declare class ChatHistoryService {
     private workspaceRoot;
     /** The maximum number of chat sessions allowed in the cache. Oldest sessions are discarded when this limit is exceeded. */
     private readonly MAX_SESSIONS;
+    /** Default maximum entries allowed in active history before automatic archiving. */
+    private readonly DEFAULT_MAX_HISTORY_ENTRIES;
+    /** Default maximum estimated tokens before pruning. */
+    private readonly DEFAULT_MAX_TOKENS;
     /**
      * Initializes the chat history service with the workspace root path.
      * This must be called before attempting to read, save, or delete sessions.
@@ -65,15 +91,82 @@ declare class ChatHistoryService {
      * @returns An array of saved `ChatSessionData` objects, ordered as stored in the cache.
      */
     getSessions(): ChatSessionData[];
+    /**
+     * Retrieves a single chat session by ID.
+     *
+     * @param id - The unique session identifier.
+     * @returns The session data, or null if not found.
+     */
+    getSession(id: string): ChatSessionData | null;
+    /**
+     * Estimates the total token count of all messages within a given chat session.
+     *
+     * @param session The chat session to evaluate.
+     * @returns Total estimated tokens.
+     */
+    estimateSessionTokens(session: ChatSessionData): number;
+    /**
+     * Validates and cleans conversation turns by removing empty parts or invalid structures.
+     *
+     * @param history Array of Content objects.
+     * @returns Sanitized array of Content objects.
+     */
+    sanitizeSessionHistory(history: Content[]): Content[];
+    /**
+     * Appends pruned history items to the session's archive JSON file on disk.
+     *
+     * @param id - The session identifier.
+     * @param prunedEntries - Array of pruned Content objects.
+     */
+    archiveSessionHistory(id: string, prunedEntries: Content[]): Promise<void>;
+    /**
+     * Retrieves previously archived history entries for a given session.
+     *
+     * @param id - The session identifier.
+     * @returns Array of archived Content objects.
+     */
+    getArchivedSessionHistory(id: string): Promise<Content[]>;
+    /**
+     * Prunes a session's history to satisfy entry and token bounds while preserving
+     * recent conversational context and alternating turn integrity.
+     *
+     * @param session The session to prune.
+     * @param options History pruning configuration options.
+     * @returns An object containing the pruned session and count of archived entries.
+     */
+    pruneSessionHistory(session: ChatSessionData, options?: HistoryPruneOptions): Promise<{
+        prunedSession: ChatSessionData;
+        archivedCount: number;
+    }>;
     /**
      * Saves or updates a chat session in the local workspace cache.
      * If a session with the same ID already exists, it is updated in place. Otherwise, it is appended.
+     * Automatically executes history pruning and archiving if the session exceeds token/turn thresholds.
      * Enforces the maximum session limit of 250 by removing the oldest session if the limit is exceeded.
      *
      * @param session - The chat session data to be saved.
+     * @param pruneOptions - Optional pruning configuration overrides.
      * @returns A promise that resolves when the session has been successfully written to the cache.
      */
-    saveSession(session: ChatSessionData): Promise<void>;
+    saveSession(session: ChatSessionData, pruneOptions?: HistoryPruneOptions): Promise<void>;
+    /**
+     * Retrieves a chat session with its history constrained to a specific token budget.
+     *
+     * @param id - The unique session identifier.
+     * @param maxTokens - Maximum token budget for the returned history.
+     * @returns The session with budget-constrained history, or null if session not found.
+     */
+    getSessionWithTokenBudget(id: string, maxTokens: number): Promise<ChatSessionData | null>;
+    /**
+     * Prunes stale sessions based on age (in days) or total count limit.
+     *
+     * @param options Pruning options specifying maxAgeDays and maxTotalSessions.
+     * @returns Number of sessions pruned.
+     */
+    pruneOldSessions(options?: {
+        maxAgeDays?: number;
+        maxTotalSessions?: number;
+    }): Promise<number>;
     /**
      * Updates the user-friendly title of an existing chat session in the local workspace cache.
      * If the session with the matching ID exists, its title is updated and persisted to `chat_sessions.json`.