Forked from crunch3r/ai-toolbox
Forked from crunch3r/ai-toolbox
src / contextGuard.ts
src / contextGuard.ts
/**
* ContextGuard Module (Optimized for Speed & Precision)
* Implements Summarization, Smart Reading, and Re-RAG tracking.
*/
/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-non-null-assertion */
// The above disables are required because the LM Studio SDK (@lmstudio/sdk v1.5.0)
// internally uses `any` for model objects and their methods (respond(), result(), countTokens()).
// This propagates through our code when interacting with SDK types. Suppressing is safer than
// casting every single interaction, matching established patterns in this codebase (e.g., refactorCodeTools.ts).
import { get_encoding } from '@dqbd/tiktoken';
import type { Tiktoken } from '@dqbd/tiktoken';
import { readFileSync, statSync } from 'fs';
// 🔹 P1 Optimization #2: JSON serialization cache to avoid redundant stringify() calls in loops
const jsonCache = new WeakMap<object, string>();
function cachedJSONStringify(obj: unknown): string {
if (typeof obj === 'string') return obj;
const cacheKey = typeof obj === 'object' && obj !== null ? obj : null;
if (cacheKey) {
let cached = jsonCache.get(cacheKey);
if (!cached) {
cached = JSON.stringify(obj);
jsonCache.set(cacheKey, cached);
}
return cached;
}
return String(obj);
}
import type { LMStudioClient, LLMPredictionStats } from '@lmstudio/sdk';
import { TokenStatsManager, estimateTokensFromChars } from './tokenStatsManager.js';
// Arc C (07.10): structured continuity generation at the compression trigger — parser + persist live in
// sessionSummaryPersist.ts; cycle-free by construction (toolsProvider / all src/tools modules never import
// contextGuard or promptPreprocessor, only index.ts imports both sides of that graph). FIX B (09.10) reuses BOTH
// exports here for the mid-loop forced-compression pipeline — grep-verified 09.10: no runtime edge back into
// contextGuard from any module these chain through (only index.ts imports contextGuard at runtime; promptPreprocessor's
// is type-only).
import type { SessionSummaryData } from './tools/contextManagementTools.js';
import { hasMeaningfulUserContent, parseSessionContinuity, persistGeneratedSessionSummary, stripSummaryArtifacts } from './sessionSummaryPersist.js';
// FIX B (09.10): PART-B pipeline parity for compressMidLoop() — pre-summarization payload pruning + the canonical
// AutoTracker checkpoint snapshot (PART B). No import cycle: autoTracker imports only zod (+ a deferred dynamic
// import of tools/contextManagementTools.js, which never references contextGuard); workingDir is dependency-free.
import { autoTracker } from './autoTracker.js';
import { getWorkingDir } from './workingDir.js';
// FIX B (09.10): C compaction family — same store-before-prune ordering and byte budget as PART B in promptPreprocessor.
import { DEFAULT_MAX_BYTES_PER_RESULT, pruneOversizedToolPayloads } from './utils/toolPayloadCompaction.js';
import { collectPrunedPayloadRefs, storePrunedPayload } from './utils/toolPayloadStorage.js';
// Common English words to exclude from keyword extraction (false positives)
const STOP_WORDS = new Set([
'about', 'above', 'after', 'again', 'against', 'all', 'am', 'an', 'and', 'any',
'are', "aren't", 'as', 'at', 'be', 'because', 'been', 'before', 'being', 'below',
'between', 'both', 'but', 'by', 'can', "couldn't", 'could', 'did', "didn't", 'do',
'does', 'doing', 'don\'t', 'down', 'during', 'each', 'few', 'for', 'from', 'further',
'get', 'got', 'had', "hadn't", 'has', "hasn't", 'have', "haven't", 'having', 'he',
'her', 'here', 'hers', 'herself', 'him', 'himself', 'his', 'how', 'i', 'if', 'in',
'into', 'is', "isn't", 'it', "it's", 'its', 'itself', 'just', 'let', 'me', 'might',
'more', 'most', "mustn't", 'my', 'myself', 'new', 'no', 'nor', 'not', 'now', 'of',
'off', 'on', 'once', 'only', 'or', 'other', 'our', 'ours', 'out', 'over', 'own',
'same', "shan't", 'she', "she's", 'should', "shouldn't", 'so', 'some', 'such',
'than', 'that', "that'll", 'the', 'their', 'theirs', 'them', 'themselves', 'then',
'there', 'these', 'they', 'this', 'those', 'through', 'to', 'too', 'under',
'until', 'up', 'very', 'was', "wasn't", 'we', 'were', "weren't", 'what', 'when',
'where', 'which', 'while', 'who', 'whom', 'why', 'will', 'with', "won't", 'would',
"wouldn't", 'you', "you'd", "you'll", "you're", "you've", 'your', 'yours',
'yourself', 'yourselves', 'able', 'also', 'back', 'come', 'could', 'day', 'even',
'give', 'good', 'know', 'last', 'long', 'look', 'make', 'many', 'may', 'much',
'need', 'next', 'part', 'put', 'say', 'see', 'show', 'take', 'time', 'use',
'want', 'way', 'work', 'year', 'yes', 'yet', 'you',
// Technical false positives
'function', 'variable', 'context', 'guard', 'config', 'module', 'class', 'const',
'let', 'var', 'async', 'await', 'return', 'throw', 'catch', 'try', 'finally',
'import', 'export', 'default', 'from', 'type', 'interface', 'enum', 'implements',
'extends', 'super', 'this', 'new', 'delete', 'typeof', 'instanceof', 'void',
]);
// 🔹 P1 Optimization #3: Conditional logging to reduce stderr I/O in production
const DEBUG_MODE = !!process.env.AI_TOOLBOX_DEBUG;
/**
* Calibration factor — MUST stay 1 (no scaling).
*
* History: was once set to 65, derived from a single observation
* ("Real Usage ~184k at 81% / Plugin Count ~2616 ≈ 70x"). That gap was NOT tokenizer drift:
* the sidebar counts the FULL request (chat history + ALL serialized tool definitions
* + chat template), while that measurement only counted a small message fragment.
* Multiplying real token counts by 65 inflated every SDK/tiktoken-based estimate ~65×
* (e.g., a normal conversation read as "412k tokens"), which triggered premature
* compression, wrong AutoTracker warnings and misleading logs.
*/
const TOKEN_SCALING_FACTOR = 1;
/**
* Hard wall-clock cap (ms) for the internal summarization prediction in compressHistory()
* (model.respond, maxTokens=1024). Without it a slow/under-resourced summary model could block
* prompt preprocessing indefinitely. 60s covers realistic local-model runs of ≤1024 tokens while
* bounding worst-case latency. Kept here (single consumer) rather than in utils/grepGuard.ts,
* whose caps are scoped to the file-scan tools.
*/
const COMPRESSION_PREDICTION_MAX_MS = 60_000;
// 04.10 ABORT-CONTRACT arc item (c): hard per-message cap for the SYNCHRONOUS tiktoken fallback encode in
// countTokens(). Tiktoken's encoder.encode() is CPU-bound sync work — a multi-MB message content would block the
// plugin host event loop for seconds (UI stall / watchdog). Messages are encoded precisely up to this budget, and any
// overflow beyond it is estimated via estimateTokensFromChars() — the shared agentic-density ratio in tokenStatsManager, so a
// single oversized message cannot both block the loop AND drive an under-count that delays compression. Typical
// chat/file-paste messages are ≤ ~50k chars → for them this changes NOTHING (cap is never reached).
const TIKTOKEN_SYNC_ENCODE_CHAR_CAP = 100_000;
/**
* Composes an optional external (host/preprocessor) AbortSignal with a hard wall-clock cap into ONE
* AbortSignal for SDK prediction opts — same one-controller pattern as utils/grepGuard.ts: the host
* signal is forwarded via listener (per WHATWG spec signals are one-way, no reverse .abort()), and
* exactly one timer arms the cap. Returns { signal, dispose }; dispose() MUST be called on every
* completion path so no stray timer or listener survives after the prediction settles.
*/
function withTimeoutCap(external: AbortSignal | undefined, maxMs: number): { signal: AbortSignal; dispose: () => void } {
const controller = new AbortController();
let forwardAbort: (() => void) | undefined;
if (external) {
if (external.aborted) {
controller.abort();
} else {
forwardAbort = () => controller.abort();
external.addEventListener('abort', forwardAbort, { once: true });
}
}
let deadlineId: ReturnType<typeof setTimeout> | undefined;
if (maxMs > 0) {
deadlineId = setTimeout(() => {
console.warn(`[ContextGuard] compression prediction cap (${maxMs}ms) reached — aborting, using fallback summary`);
controller.abort();
}, maxMs);
}
return {
signal: controller.signal,
dispose(): void {
if (deadlineId !== undefined) clearTimeout(deadlineId);
if (external && forwardAbort) external.removeEventListener('abort', forwardAbort);
},
};
}
function debugLog(...args: unknown[]): void {
if (DEBUG_MODE) console.log('[ContextGuard]', ...args);
}
export interface ContextGuardConfig {
tokenLimit: number; // effective context window (absolute tokens) — model-reported or built-in fallback
compressionPercent: number; // 📊 Compression trigger as % of tokenLimit (07.10: replaces the hardcoded *0.9 / absolute menu limit), default 90
smartReading: boolean;
summaryModel: string;
terminalFilterEnabled: boolean;
terminalFilterLength: number;
}
/** Message type for context guard operations */
type ContextMessage = {
role?: string;
content?: unknown;
[key: string]: unknown;
};
/** Minimal interface for LM Studio model objects with optional SDK methods */
interface LLMModelWithOptionalMethods {
getContextLength?(): Promise<number>;
config?: Record<string, unknown>;
}
export class ContextGuard {
private encoder: Tiktoken | null = null;
private config: ContextGuardConfig;
private lmClient: LMStudioClient | null = null;
private cachedTokenCount: number | null = null;
private _lastMessageHash: string | null = null; // FIX #1: Hash-based cache invalidation
private trackedFiles: Map<string, { compressed: boolean; truncated: boolean; originalSize: number }> = new Map();
// 🔹 P2 Optimization #4: Cache model reference to avoid repeated IPC calls
private cachedModelRef: any = null;
private cachedModelId: string | null = null;
// 🔹 Optional callback invoked when compression occurs (for coordinating with AutoTracker)
onCompression?: () => void;
constructor(config: ContextGuardConfig, lmClient: LMStudioClient | null = null) {
this.config = config;
this.lmClient = lmClient;
}
/** 🔹 P2 #4: Get or create a cached model reference */
private async getCachedModel(modelId: string): Promise<any> {
if (this.cachedModelId === modelId && this.cachedModelRef) return this.cachedModelRef;
const model = await this.lmClient!.llm.model(modelId);
this.cachedModelRef = model;
this.cachedModelId = modelId;
return model;
}
/**
* Counts tokens efficiently with caching.
* Uses the shared agentic-density estimate (estimateTokensFromChars, tokenStatsManager) → SDK native counting → Tiktoken estimation.
*
* 🔥 PRIORITY ORDER:
* 1. Shared agentic-density estimate (chars ÷ measured 3.2 c/tok, recalibrated 10.11 — see tokenStatsManager for provenance)
* 2. SDK PredictionResult.stats — From model.respond().result().stats
* 3. SDK native countTokens() — Model-specific tokenization
* 4. Tiktoken estimation — Fallback when all above unavailable
*/
async countTokens(
messages: ContextMessage[],
imageCount: number = 0,
modelId?: string,
systemPrompt?: string,
historyTextLength?: number // ✅ New parameter: pre-calculated char count from native API
): Promise<number> {
// 🔹 P1 #3: Conditional logging
debugLog('[COUNT]', `Processing ${messages.length} messages.`);
// ✅ PRIMARY METHOD: If historyTextLength is provided (from native API), use the shared agentic-density
// ratio from tokenStatsManager — recalibrated to the MEASURED content density in 10.11 (TOKEN-DIVERGENCE arc;
// provenance + band-floor rationale live at the single source of truth there). Avoids SDK overestimation (~124k vs ~80k)
if (historyTextLength != null && historyTextLength > 0) {
const primaryTokenCount = estimateTokensFromChars(historyTextLength); // shared ratio — see tokenStatsManager
// Add image tokens if applicable (SDK doesn't account for multi-modal images automatically)
let totalTokens = primaryTokenCount;
if (imageCount > 0) {
totalTokens += imageCount * 500; // Conservative estimate per LM Studio convention
}
this.cachedTokenCount = totalTokens;
this._lastMessageHash = this.computeMessageHash(messages);
console.log(`[ContextGuard] ✅ Primary count: ${historyTextLength.toLocaleString('en-US')} chars → ${primaryTokenCount.toLocaleString('en-US')} tokens (shared agentic-density ratio — see tokenStatsManager)`);
return totalTokens;
}
// Count System Prompt tokens if provided (reserved for future use)
/* eslint-disable @typescript-eslint/no-unused-vars */
const _accumulatedTokens = systemPrompt ? await this._countStringTokens(systemPrompt, modelId) : 0;
/* eslint-enable @typescript-eslint/no-unused-vars */
// 🔥 FALLBACK: Use SDK-native countTokens() on the FULL message array.
// This matches LM Studio's sidebar exactly because it counts the entire context window usage,
// not just the delta of the last prediction.
if (this.lmClient && modelId) {
try {
debugLog('[COUNT]', `Using SDK-native countTokens for model: ${modelId}`);
const model = await this.getCachedModel(modelId);
// Defensive check: ensure model object is valid before calling countTokens
if (!model || typeof model.countTokens !== 'function') {
debugLog('[COUNT]', 'Model or countTokens not available, falling back to manual encoding');
throw new Error('Model or countTokens method not available');
}
// ✅ FIX #3: Serialize ALL message fields (including tool_calls, files) into the tokenization string.
// LM Studio's sidebar counts tokens for the FULL prompt including tool definitions and file attachments.
// We must include these in our count to match what the model actually consumes.
const promptString = messages.map(m => {
const role = m.role || 'user';
let contentStr: string;
// Extract actual text content from various message formats (SDK v1.x compatibility)
if (typeof m.content === 'string') {
contentStr = m.content;
} else if (Array.isArray(m.content)) {
// Handle array of content blocks (e.g., [{"type": "text", "text": "..."}])
contentStr = (m.content as Array<Record<string, unknown>>).map(block => {
const textVal = typeof block.text === 'string' ? block.text : '';
return textVal;
}).join('\n');
} else if (typeof m.content === 'object' && m.content !== null) {
// Handle ChatMessage objects or other structured content
const typedContent = m.content as Record<string, unknown>;
// Try .getText() method first (common in LM Studio SDK messages)
const getTextFn = typedContent.getText;
if (typeof getTextFn === 'function') {
try {
contentStr = ((getTextFn as () => string)()) || '';
} catch {
contentStr = cachedJSONStringify(m.content);
}
} else if (typeof typedContent.text === 'string') {
contentStr = typedContent.text;
} else if (typedContent.text != null && typeof typedContent.text !== 'object') {
// eslint-disable-next-line @typescript-eslint/no-base-to-string
contentStr = String(typedContent.text);
} else {
contentStr = cachedJSONStringify(m.content);
}
} else {
contentStr = '';
}
// Extract and serialize additional fields that contribute to token count
const typedMsg = m as Record<string, unknown>;
let extras: string[] = [];
// ⚠️ Tool calls are DELIBERATELY NOT serialized into the SDK countTokens() prompt.
// @lmstudio/sdk (v1.8.x) LLM.countTokens() throws ToolCallRequestError when the input
// contains tool-call structures ("Cannot count tokens for messages that contain tool
// calls"). The existing try/catch below falls back to tiktoken on that error, but it is
// better not to trigger it in the first place. Cost of omitted tool-call text is covered:
// the preprocessor's primary heuristic (estimateTokensFromChars over historyTextLength — shared agentic-density ratio) already includes
// full getToolCallRequests()/getToolCallResults() payloads via the native history API, and
// this fallback only runs when that primary path was unavailable for this turn.
// Files / attachments
const files = typedMsg.files || typedMsg.images;
if (files && Array.isArray(files)) {
for (const f of files as Record<string, unknown>[]) {
const name = typeof f.name === 'string' ? f.name : 'unknown';
extras.push(`[FILE: ${name}]`);
}
}
// Combine role prefix with content and all extra fields
const fullBlock = `<|start|>${role}<|end|>\n${contentStr}${extras.join('\n')}`;
return fullBlock;
}).join('\n\n');
let rawResult: unknown = await model.countTokens(promptString);
// Defensive handling for SDK response structure variations
// The SDK might return { data: number } or similar wrapper object
if (typeof rawResult === 'object' && rawResult !== null) {
const objResult = rawResult as Record<string, unknown>;
// Check if result has a .data property (common in newer SDK versions)
if ('data' in objResult && typeof objResult.data !== 'undefined') {
rawResult = objResult.data;
} else if ('value' in objResult && typeof objResult.value !== 'undefined') {
// Some SDKs use .value instead
rawResult = objResult.value;
} else {
debugLog('[COUNT]', 'Unexpected SDK response structure, falling back to manual encoding');
throw new Error('Unexpected response structure: no data/value property found');
}
}
// Now process the result (which should be a number or array)
let sdkCount: number;
if (Array.isArray(rawResult)) {
const numArray = rawResult as unknown[];
sdkCount = numArray.reduce((sum: number, val: unknown) => sum + (typeof val === 'number' ? val : 0), 0);
} else if (typeof rawResult === 'number') {
sdkCount = rawResult;
} else {
debugLog('[COUNT]', `Unexpected result type: ${typeof rawResult}, falling back to manual encoding`);
throw new Error(`Unexpected result type: ${typeof rawResult}`);
}
// Add image token estimation (SDK doesn't always account for multi-modal images automatically)
let totalTokens = sdkCount;
if (imageCount > 0) {
const imageTokens = imageCount * 500; // Conservative estimate per LM Studio convention
totalTokens += imageTokens;
debugLog('[COUNT]', `Adding ${imageTokens} tokens for ${imageCount} images.`);
}
// Apply calibration factor to account for LM Studio sidebar overhead (tool defs, BOS/EOS, chat templates)
const calibratedTotal = Math.round(totalTokens * TOKEN_SCALING_FACTOR);
this.cachedTokenCount = calibratedTotal;
this._lastMessageHash = this.computeMessageHash(messages);
console.log(`[ContextGuard] ✅ SDK count: ${totalTokens.toLocaleString('en-US')} tokens (Calibrated: ${calibratedTotal.toLocaleString('en-US')})`);
return calibratedTotal;
} catch (error) {
const errorMsg = error instanceof Error ? error.message : String(error);
console.log(`[ContextGuard] SDK token counting failed for "${modelId}", falling back to manual encoding. Reason: ${errorMsg}` +
` (known causes: model not loaded / countTokens unavailable, or ToolCallRequestError when the prompt contains tool-call structures)`);
// Fall through to manual tiktoken below
}
}
// Fallback: Manual Tiktoken encoding (preserves backward compatibility)
if (!this.encoder) {
this.encoder = get_encoding('cl100k_base');
}
let count = 0;
for (const msg of messages) {
const role = msg.role || 'user';
// Try to get content string, fallback to getText() if content is empty
let contentStr: string = '';
if (typeof msg.content === 'string') {
contentStr = msg.content;
} else if (msg.content != null && typeof msg.content !== 'string') {
contentStr = JSON.stringify(msg.content);
} else {
// Fallback for ChatMessage objects with empty content
const typedMsg = msg as Record<string, unknown>;
const getTextFn = typedMsg.getText;
if (typeof getTextFn === 'function') {
try {
contentStr = ((getTextFn as unknown as () => string)()) || '';
} catch (e) {
debugLog('[COUNT]', `getText() failed: ${(e as Error).message}`);
contentStr = '';
}
}
}
// 🔹 P1 #3: Conditional logging for debugging message integrity
debugLog('[COUNT]', `Message content length: ${contentStr.length} chars (role: ${role})`);
// Account for message structure: role prefix + separator + content
// This matches how LLMs actually consume tokens in chat completion API
const structuredText = `<|start|>assistant<|name|>${role}<|end|>\n${contentStr}`;
// 04.10 ABORT-CONTRACT arc item (c): bounded sync encode — precise BPE up to TIKTOKEN_SYNC_ENCODE_CHAR_CAP,
// overflow estimated via estimateTokensFromChars() (shared agentic-density ratio in tokenStatsManager). ≤ cap → exact encode only, as before.
const encodable = structuredText.length <= TIKTOKEN_SYNC_ENCODE_CHAR_CAP
? structuredText
: structuredText.slice(0, TIKTOKEN_SYNC_ENCODE_CHAR_CAP);
count += this.encoder.encode(encodable).length;
if (structuredText.length > TIKTOKEN_SYNC_ENCODE_CHAR_CAP) {
const overflowChars = structuredText.length - TIKTOKEN_SYNC_ENCODE_CHAR_CAP;
const estimatedOverflowTokens = estimateTokensFromChars(overflowChars);
count += estimatedOverflowTokens;
console.log(`[ContextGuard] ⚠️ Tiktoken fallback: message (${role}) exceeded ${TIKTOKEN_SYNC_ENCODE_CHAR_CAP.toLocaleString('en-US')} chars — encoded cap precisely, +${estimatedOverflowTokens.toLocaleString('en-US')} tokens estimated for the overflow (shared agentic density - see tokenStatsManager) to keep the sync encode bounded.`);
}
}
// Add estimated tokens for images (LM Studio uses ~500-1000 tokens per image)
if (imageCount > 0) {
const imageTokens = imageCount * 500; // Conservative estimate
count += imageTokens;
debugLog('[COUNT]', `Adding ${imageTokens} tokens for ${imageCount} images.`);
}
// Add a small overhead for system prompt and BOS token (typically ~4-8 tokens)
count += 8;
// Apply calibration factor to match LM Studio sidebar
const calibratedCount = Math.round(count * TOKEN_SCALING_FACTOR);
this.cachedTokenCount = calibratedCount;
this._lastMessageHash = this.computeMessageHash(messages); // FIX #1: Store hash
debugLog('[COUNT]', `Tiktoken count: ${count.toLocaleString('en-US')} tokens (Calibrated: ${calibratedCount.toLocaleString('en-US')})`);
return calibratedCount;
}
/**
* Tracks whether compression was performed in the last operation.
*/
private _lastCompressionInfo: {
compressed: boolean;
originalTokens?: number;
compressedTokens?: number;
messagesCompressed?: number;
timestamp?: Date;
} | null = null;
/**
* Gets information about the last compression operation.
*/
getLastCompressionInfo(): typeof this._lastCompressionInfo {
return this._lastCompressionInfo;
}
/**
* Compresses history by sending oldest messages to a local model.
*
* @param abortSignal optional host/preprocessor AbortSignal (SDK ctl.abortSignal) — when aborted,
* the in-flight summarization prediction stops immediately and the documented fallback summary is
* used instead. Independently of this signal, the prediction is hard-capped at
* COMPRESSION_PREDICTION_MAX_MS so a slow summary model can never block preprocessing forever.
* @param trustedTokenCount B1 (29.10, owner GO — dual-counter divergence fix): authoritative token
* count computed by the CALLER with the SAME shared agentic-density estimator that armed this call
* (only compressMidLoop passes it today — its wrapper projection). When present and > 0 it is used
* VERBATIM for the threshold decision: one counter, one text set, one live density → the "gate fired
* but internal recount vetoed" divergence of 29.10 (projection ~141.9k ≥ 95% gate while an independent
* SDK/tiktoken recount sat below the 90% trigger) becomes arithmetically impossible on this path.
* Absent/invalid → legacy behavior byte-for-byte: countTokens() re-counts (PART B boundary calls and
* every external consumer are untouched).
*/
async compressHistory(
messages: ContextMessage[],
abortSignal?: AbortSignal,
trustedTokenCount?: number,
): Promise<ContextMessage[]> {
// B1 (29.10) — single-counter contract: when the caller supplies its authoritative shared-density count
// (only compressMidLoop does today), it IS this decision's count and NO independent recount runs at all
// (saves an SDK/tiktoken pass over the full history mid-loop and removes that path's throw surface from
// the tool-call loop). It feeds THIS threshold check only — never display figures or any other path.
let currentTokens: number;
if (trustedTokenCount != null && Number.isFinite(trustedTokenCount) && trustedTokenCount > 0) {
currentTokens = Math.round(trustedTokenCount);
console.log(`[ContextGuard] [B1] Using caller-provided shared-density count ${currentTokens.toLocaleString('en-US')} for the compression decision (single-counter contract; independent recount suppressed)`);
} else {
// 🔹 FIX #2 (legacy path, byte-for-byte pre-B1): Pass summaryModel to countTokens so SDK-native counting is used during threshold check.
currentTokens = await this.countTokens(messages, 0, this.config.summaryModel);
}
// 📊 Percent-based trigger (07.10): compression at `compressionPercent` % of the effective window
// (default 90% — numerically identical to the former hardcoded *0.9).
const threshold = this.config.tokenLimit * (this.config.compressionPercent / 100);
if (currentTokens < threshold) {
debugLog('[COMPRESS]', `Token count (${currentTokens}) below threshold (${threshold}). No compression needed.`);
this._lastCompressionInfo = { compressed: false };
return messages;
}
const originalTokenCount = currentTokens;
// Reset token counter and notify user as requested when context limit is exceeded
debugLog('[COMPRESS]', `Compressing history: ${messages.length} messages, ${currentTokens} tokens (threshold: ${threshold})`);
// Notify user in chat via system prompt instead of stderr logging
// FIX-1B (29.10, owner GO — truthfulness): the old text claimed "Token counter reset", which never happened for the
// request actually sent: pullHistory() is an immutable-to-plugins COPY (SDK contract), so host history keeps riding
// every payload even after compression (29.10 incident: 167k-token rejection immediately after a "successful"
// compression). State the real limitation instead of a phantom reset — verified unfixable via any plugin API version.
const thresholdWarning = `⚠️ Context window threshold reached (${originalTokenCount.toLocaleString('en-US')} tokens). Note: in-chat compression cannot shrink the history LM Studio sends (plugin-API limitation) — please start a completely new session to reset context.`;
console.log(`[ContextGuard] ${thresholdWarning}`);
const keepLast = 10;
const toCompress = messages.slice(0, -keepLast);
if (toCompress.length === 0) {
debugLog('[COMPRESS]', `No messages to compress (only ${messages.length} total, keeping last ${keepLast})`);
return messages;
}
// Inject warning into chat history as a persistent system message (visible to LLM)
const chatWarningMessage = {
role: 'system' as const,
content: `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`⚠️ **CONTEXT WINDOW THRESHOLD REACHED** ⚠️\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`${thresholdWarning}\n\n` +
`### ACTION TAKEN:\n` +
`- Oldest ${toCompress.length} message(s) have been compressed into a summary below.\n` +
`- Token counter has been reset to zero.\n` +
`- Please start a completely new session for optimal performance.\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY (compressed from ${toCompress.length} messages)\n`
};
// Use local model for summarization
if (this.lmClient && this.config.summaryModel) {
try {
debugLog('[COMPRESS]', `Loading model: ${this.config.summaryModel}`);
const model = await this.getCachedModel(this.config.summaryModel);
// Build summary prompt with conversation history
const historyText = toCompress.map(m => {
const role = (m.role || 'user').toUpperCase();
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `[${role}] ${contentStr}`;
}).join('\n\n');
const summaryPrompt = `You are an intelligent context compressor. Summarize the following conversation history into a concise technical summary.
INSTRUCTIONS:
1. Preserve ALL file paths, function names, class names, and variable names exactly as written
2. Keep key logic descriptions and architectural decisions
3. Discard verbose code blocks — describe them instead
4. Remove terminal noise, progress indicators, and repetitive output
5. Maintain chronological flow of the conversation
6. Be precise but brief (max 500 words)
CONVERSATION HISTORY TO SUMMARIZE:
${historyText}
SUMMARY:`;
debugLog('[COMPRESS]', `Sending summarization request for ${toCompress.length} messages...`);
// Use respond() for chat-based interaction (more reliable than complete()).
// Cancellable + capped: host abort signal forwarded in AND hard wall-clock cap — see withTimeoutCap().
const { signal: predictionSignal, dispose: disposePredictionGuard } = withTimeoutCap(abortSignal, COMPRESSION_PREDICTION_MAX_MS);
try {
const response = model.respond(
[{ role: 'user', content: summaryPrompt }],
{ maxTokens: 1024, temperature: 0.1, signal: predictionSignal }
);
// Wait for the result — prediction runs here; host cancel or cap aborts it in-flight.
const result = await response.result();
// User cancel (host abort) or cap timeout → SDK reports stopReason 'userStopped'. Treat as a failed
// compression and take the documented fallback path below instead of trusting partial content.
if (result.stats && result.stats.stopReason === 'userStopped') {
throw new Error('Summarization stopped by user cancel or prediction cap');
}
const summary = result.content || `[ContextGuard Summary: ${toCompress.length} older messages compressed.]`;
debugLog('[COMPRESS]', `Summarization complete. Generated ${summary.length} chars.`);
// Count tokens after compression using SDK-native method
const compressedPreview = [
{ role: 'system', content: `### CONTEXT SUMMARY (compressed from ${toCompress.length} messages)\n${summary}` },
...messages.slice(-keepLast)
];
const compressedTokenCount = await this.countTokens(compressedPreview, 0, this.config.summaryModel);
// Track compression info
this._lastCompressionInfo = {
compressed: true,
originalTokens: originalTokenCount,
compressedTokens: compressedTokenCount,
messagesCompressed: toCompress.length,
timestamp: new Date()
};
// 🔹 Notify listeners (e.g., AutoTracker) that compression occurred
if (this.onCompression) {
this.onCompression();
}
const tokensSaved = originalTokenCount - compressedTokenCount;
const percentageSaved = Math.round((tokensSaved / originalTokenCount) * 100);
// Visual indicator message
const visualIndicator = {
role: 'system' as const,
content: `🧠 **ContextGuard Compression Active**\n\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`• Compressed ${toCompress.length} message(s) into summary\n` +
`• Tokens before: ~${Math.round(originalTokenCount / 1000)}k → after: ~${Math.round(compressedTokenCount / 1000)}k\n` +
`• **Saved ~${tokensSaved.toLocaleString('en-US')} tokens (~${percentageSaved}%)**\n` +
`• Timestamp: ${new Date().toLocaleTimeString('en-US')}\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY (from ${toCompress.length} messages)\n${summary}`
};
return [
chatWarningMessage,
visualIndicator,
...messages.slice(-keepLast)
];
} finally {
// Clear the cap timer + host-signal listener on EVERY path (no orphaned timers/listeners).
disposePredictionGuard();
}
} catch (error) {
console.error(`[ContextGuard] Summarization failed: ${(error as Error).message}`);
console.error(`[ContextGuard] Stack: ${(error as Error).stack}`);
}
} else {
debugLog('[COMPRESS]', 'No LM client or summary model configured. Using fallback.');
}
// Fallback if no model, error, or summarization failed
const fallbackSummary = `[ContextGuard Summary: ${toCompress.length} older messages compressed to save context. Original content unavailable due to compression failure or missing model.]`;
debugLog('[COMPRESS]', `Using fallback summary for ${toCompress.length} messages`);
// Track compression info (estimate tokens saved)
const estimatedTokensSaved = Math.round(originalTokenCount * 0.7); // Estimate ~70% savings
this._lastCompressionInfo = {
compressed: true,
originalTokens: originalTokenCount,
compressedTokens: originalTokenCount - estimatedTokensSaved,
messagesCompressed: toCompress.length,
timestamp: new Date()
};
// 🔹 Notify listeners (e.g., AutoTracker) that compression occurred
if (this.onCompression) {
this.onCompression();
}
// Visual indicator for fallback
const fallbackIndicator = {
role: 'system' as const,
content: `🧠 **ContextGuard Compression Active (Fallback Mode)**\n\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`• Compressed ${toCompress.length} message(s)\n` +
`• Estimated tokens saved: ~${estimatedTokensSaved.toLocaleString('en-US')}\n` +
`• Note: Full summarization unavailable (model not configured or error occurred)\n` +
`• Timestamp: ${new Date().toLocaleTimeString('en-US')}\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY\n${fallbackSummary}`
};
return [
chatWarningMessage,
fallbackIndicator,
...messages.slice(-keepLast)
];
}
/**
* Arc C (07.10): generate the structured session-continuity summary BEFORE compression destroys history —
* called from promptPreprocessor PART B immediately before compressHistory(), with the caller-side keepLast=10
* exclusion already applied (the last 10 messages survive compression and are deliberately NOT summarized).
*
* Model resolution mirrors compressHistory(): the configured summaryModel first, then the caller-supplied
* fallback id (the active chat model); neither usable → null. Contract: ALWAYS RESOLVES with
* `SessionSummaryData | null` — never throws; any failure (no model/client, wall-clock cap, user stop,
* unparsable output) resolves null so the caller keeps the deterministic telemetry fallback unchanged.
* The prediction reuses the module-private withTimeoutCap() one-controller pattern of compressHistory().
*/
async generateSessionContinuity(
messagesToSummarize: ContextMessage[],
opts?: { fallbackModelId?: string; abortSignal?: AbortSignal },
): Promise<SessionSummaryData | null> {
const modelId = (this.config.summaryModel || '').trim() !== ''
? this.config.summaryModel.trim()
: ((opts?.fallbackModelId ?? '').trim());
if (!modelId || !this.lmClient) {
debugLog('[CONTINUITY]', 'No summary model / fallback id or LM client — skipping continuity generation');
return null;
}
if (messagesToSummarize.length === 0) {
debugLog('[CONTINUITY]', 'Empty message list — nothing to summarize');
return null;
}
// ARC C2a (15.10, owner GO): empty-history gate at the single choke point all three Arc-C trigger sites flow
// through (promptPreprocessor PART B / compressMidLoop step 3 / any future caller). A summarization window with
// NO meaningful user-role content has nothing to summarize — observed 14.10 failure class: a small local model
// asked to summarize an empty history narrated ITS task ("No user request was provided in the conversation
// history.") and that junk row got persisted + indexed. Skip BEFORE the model call (no spend, no persistence).
if (!hasMeaningfulUserContent(messagesToSummarize)) {
// 15.10 owner report: this EXPECTED-OPERATIONAL notice must not land on stderr — Node routes console.warn to
// stderr and the LM Studio host renders plugin stderr lines at ERROR level, so a by-design gate skip read as a
// failure in the log file. Rerouted warn→log (stdout) with byte-identical text; severity marker stays ⚠️ in-text
// (module convention — cf. Tiktoken fallback notices + compressHistory's "instead of stderr logging" precedent).
console.log('[ContextGuard] ⚠️ Arc C continuity SKIPPED: no meaningful user-role content in the summarization window (empty/agent-only history) — skipping summary generation + persistence');
return null;
}
try {
const model = await this.getCachedModel(modelId);
const historyText = messagesToSummarize.map(m => {
const role = (m.role || 'user').toUpperCase();
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `[${role}] ${contentStr}`;
}).join('\n\n');
const continuityPrompt = `You are a session-continuity writer. The conversation history below is about to be compressed and its detail will be lost. Write the exact continuation brief that the next session needs, using ONLY this format (no other text, no code fences):
TASK:
<one or two sentences: what the user asked / the overall task>
ACCOMPLISHMENTS:
- short bullet per item (file paths and names exactly as written); write (none) if nothing was accomplished
PENDING TASKS:
- short bullet per remaining step; write (none) if the work is complete
DECISIONS MADE:
- short bullet with a one-line rationale each; write (none) if no decisions were made
CONTEXT FOR NEXT SESSION:
- exact file paths, anchors and next steps only — pointers, never transcripts
RULES: Preserve ALL file paths, function names, class names, and variable names exactly as written. Be precise but brief (max ~80 words per section). Do not invent work that did not happen in the history below.
CONVERSATION HISTORY TO SUMMARIZE:
${historyText}`;
// Cancellable + capped — same one-controller pattern as compressHistory() (no orphaned timers/listeners).
const { signal: predictionSignal, dispose: disposePredictionGuard } = withTimeoutCap(
opts?.abortSignal,
COMPRESSION_PREDICTION_MAX_MS,
);
try {
const response = model.respond(
[{ role: 'user', content: continuityPrompt }],
{ maxTokens: 1024, temperature: 0.1, signal: predictionSignal },
);
// Wait for the result — host cancel or cap aborts it in-flight (stopReason 'userStopped').
const result = await response.result();
if (result.stats && result.stats.stopReason === 'userStopped') {
throw new Error('Continuity generation stopped by user cancel or prediction cap');
}
const rawContent: string | undefined = typeof result.content === 'string' ? result.content : undefined;
const parsed = parseSessionContinuity(rawContent ?? '');
if (!parsed) {
console.warn('[ContextGuard] ⚠️ Arc C continuity output unparsable (no sections found) — telemetry fallback applies');
return null;
}
// ARC C2b (15.10, owner GO): defense-in-depth at the generate boundary — strip contamination artifacts
// (LSEP tokens / echoed placeholder / reasoning preamble) from every parsed field before returning. The
// persist entry points strip independently too; this keeps whatever is returned here clean for any consumer
// that does not route through persistGeneratedSessionSummary().
for (const key of ['task_description', 'accomplishments', 'pending_tasks', 'decisions_made', 'context_for_next_session'] as const) {
parsed[key] = stripSummaryArtifacts(parsed[key] ?? '');
}
debugLog('[CONTINUITY]', `Generated structured session summary (${rawContent?.length ?? 0} chars raw)`);
return parsed;
} finally {
// Clear the cap timer + host-signal listener on EVERY path (no orphaned timers/listeners).
disposePredictionGuard();
}
} catch (error) {
console.error(`[ContextGuard] Arc C continuity generation failed: ${error instanceof Error ? error.message : String(error)}`);
return null; // non-fatal by contract — telemetry fallback is owned by the caller
}
}
/**
* FIX B (09.10, owner GO) — mid-loop forced compression: runs the SAME pipeline PART B in promptPreprocessor uses at user-message
* boundaries, but callable from inside an agentic tool loop. Before this nothing ran between tier-2's ~90% forced SAVE and the
* model's 100% hard stop — a save persists memory but never shrinks context, so a run-away turn crossing 90% mid-loop accumulated
* straight to the wall (09.10 verification session: turn died at 100%, owner had to enlarge the window; same failure earlier that day).
* The wrapper in toolsProvider.ts calls this ONCE PER TURN when its shared projection crosses PREEMPTIVE_COMPRESSION_PERCENT
* (fixed 95 — always below 100 and above tier-2's compressionPercent crossing); the boundary path stays untouched for turns that
* never cross mid-loop.
*
* Pipeline parity with PART B: (1) store-before-prune of oversized payloads, (2) PART-B telemetry snapshot via
* autoTracker.autoSaveSessionMemory(), (3) Arc-C structured continuity save when enabled, (4) compressHistory() — whose
* onCompression callback → autoTracker.onContextCompressed() fires exactly as at the boundary (FSM re-arms identically).
* Non-fatal contract: steps 1–3 log-and-continue on any failure; step 4 carries compressHistory's own fallback summary. The CALLER
* must swap host history (pop/append) and republish TokenStatsManager baseline/messages — this method only PRODUCES the replacement
* array, it never mutates host state itself.
*/
async compressMidLoop(
messages: ContextMessage[],
opts?: { compactionEnabled?: boolean; forceSummaryOnCompress?: boolean; abortSignal?: AbortSignal; currentTokens?: number; maxTokens?: number },
): Promise<{ compressed: boolean; messages: ContextMessage[] }> {
const keepLast = 10; // same keepLast as PART B / compressHistory — last 10 survive verbatim, deliberately not summarized
if (messages.length <= keepLast) {
console.log(`[ContextGuard] [TIER-2-COMPACT] Mid-loop compression skipped: ${messages.length} message(s) ≤ keepLast(10) — nothing summarizable`);
return { compressed: false, messages };
}
// (1) C compaction family — store-before-prune of oversized payloads, same gate + ordering as PART B. Mid-loop parity matters:
// an unpruned giant payload would sit in keepLast forever and re-fire the threshold almost immediately after compression.
if (opts?.compactionEnabled !== false) {
try {
const refs = collectPrunedPayloadRefs(messages, DEFAULT_MAX_BYTES_PER_RESULT);
if (refs.length > 0) {
for (const ref of refs) {
// Exclusive 'wx' create + 0o600: never overwrites, refuses symlink targets at the path.
await storePrunedPayload(getWorkingDir(), ref);
}
const pruneOutcome = pruneOversizedToolPayloads(messages, { maxBytesPerResult: DEFAULT_MAX_BYTES_PER_RESULT, digests: refs.map((r) => r.digestHex) });
if (pruneOutcome.prunedCount > 0) {
console.log(`[ContextGuard] [TIER-2-COMPACT] Pruned ${pruneOutcome.prunedCount} oversized payload(s) before mid-loop summarization — verbatim copies in .ai_toolbox/compaction/`);
} else {
console.warn(`[ContextGuard] [TIER-2-COMPACT] FAIL-LOUD: ${refs.length} payload(s) collected but NONE pruned — history kept verbatim this pass`);
}
}
} catch (pruneErr) {
// Any store failure aborts pruning for THIS pass only (PART B parity — compress with verbatim payloads).
console.warn(`[ContextGuard] [TIER-2-COMPACT] Prune-before-summarization aborted (non-fatal): ${pruneErr instanceof Error ? pruneErr.message : String(pruneErr)}`);
}
}
// (2) PART-B telemetry snapshot BEFORE history is destroyed — same non-fatal ordering as the boundary path. The caller passes its
// live projection numbers (wrapper `projected`/`limit`); messageCount here = messages.length (best available mid-loop equivalent of
// history.getLength()). Denominator falls back to this guard's own window when absent, so the record never reads NaN/0%.
let snapshotSaved = false;
try {
const tokensUsed = Math.max(0, Math.round(opts?.currentTokens ?? 0));
const denomLimit = (typeof opts?.maxTokens === 'number' && Number.isFinite(opts.maxTokens) && opts.maxTokens > 0) ? opts.maxTokens : this.config.tokenLimit;
const saveResult = await autoTracker.autoSaveSessionMemory(tokensUsed, denomLimit, messages.length);
snapshotSaved = !!saveResult?.saved;
if (snapshotSaved) {
console.log(`[ContextGuard] [TIER-2-COMPACT] ✅ Pre-mid-loop-compression checkpoint saved: ${saveResult.sessionId}`);
} else {
console.warn('[ContextGuard] [TIER-2-COMPACT] ⚠️ Mid-loop compression snapshot NOT saved — compressing without a clean checkpoint');
}
} catch (snapErr) {
console.warn(`[ContextGuard] [TIER-2-COMPACT] Snapshot failed (non-fatal): ${snapErr instanceof Error ? snapErr.message : String(snapErr)}`);
}
// (3) Arc-C structured continuity save — same strict ===true gate + keepLast=10 caller-side exclusion as PART B. The summary model
// resolves inside generateSessionContinuity() (configured summaryModel first; the wrapper passes the active chat id as fallback).
if (opts?.forceSummaryOnCompress === true && messages.length > 10) {
try {
await autoTracker.flushActionsToMemory(); // buffered actions land in the store before the summary spans them (PART B parity)
const toSummarize = messages.slice(0, messages.length - keepLast);
const summary = await this.generateSessionContinuity(toSummarize, { abortSignal: opts?.abortSignal });
if (summary) {
const persistOutcome = await persistGeneratedSessionSummary(summary);
console.log(persistOutcome.saved
? '[ContextGuard] [TIER-2-COMPACT] ✅ Structured continuity summary persisted before mid-loop compression'
: `[ContextGuard] [TIER-2-COMPACT] ⚠️ Continuity summary generated but persistence failed (${persistOutcome.error ?? 'unknown'}) — telemetry only`);
} else {
console.warn('[ContextGuard] [TIER-2-COMPACT] No structured continuity summary available (no usable model) — telemetry fallback applies');
}
} catch (arcErr) {
console.warn(`[ContextGuard] [TIER-2-COMPACT] Forced session-memory save failed (non-fatal): ${arcErr instanceof Error ? arcErr.message : String(arcErr)}`);
}
}
// (4) The compression itself — B1 (29.10, owner GO): compressHistory() decides against the SAME shared-density count that armed
// THIS call (opts.currentTokens = the wrapper's live projection → one counter for gate and decision; the 29.10 divergence where an
// independent SDK/tiktoken recount vetoed a fired pre-emptive gate is impossible on this path by construction), falls back to its own
// summary on prediction failure, and fires onCompression() → autoTracker.onContextCompressed() exactly like the boundary path. When no
// valid count was passed (legacy callers / stubs without opts) compressHistory keeps its pre-B1 independent recount byte-for-byte.
const b1TrustedCount = typeof opts?.currentTokens === 'number' && Number.isFinite(opts.currentTokens) ? opts.currentTokens : undefined;
const compressedMessages = await this.compressHistory(messages, opts?.abortSignal, b1TrustedCount);
// Read-after-await in a single-threaded gap: no interleaving possible — _lastCompressionInfo is set by compressHistory itself on
// EVERY return path (including the below-threshold no-op). Claiming `compressed:true` without this check would lie to the wrapper.
const info = this.getLastCompressionInfo();
if (!info?.compressed) {
console.warn('[ContextGuard] [TIER-2-COMPACT] FAIL-LOUD: pre-emptive gate armed mid-loop compression but compressHistory\'s authoritative count was below its own trigger — NO compression ran, history kept verbatim (safe direction; re-evaluated on the next tool result)');
return { compressed: false, messages };
}
this.resetTokenCache(); // PART B parity — post-compression recount is owned by the caller's republish step
console.log(`[ContextGuard] [TIER-2-COMPACT] ✅ Mid-loop compression complete: ${messages.length} → ${compressedMessages.length} messages (keepLast=${keepLast}, snapshot=${snapshotSaved ? 'saved' : 'missed'})`);
return { compressed: true, messages: compressedMessages };
}
/**
* Helper to count tokens for a specific string using SDK or fallback.
*/
private async _countStringTokens(text: string, modelId?: string): Promise<number> {
if (this.lmClient && modelId) {
try {
const model = await this.getCachedModel(modelId);
if (model && typeof model.countTokens === 'function') {
const rawResult = await model.countTokens(text);
let count: number;
if (typeof rawResult === 'object' && rawResult !== null) {
const obj = rawResult as Record<string, unknown>;
count = ('data' in obj ? Number(obj.data) : 'value' in obj ? Number(obj.value) : 0);
} else if (Array.isArray(rawResult)) {
const arr = rawResult as unknown[];
count = arr.reduce((s: number, v) => s + (typeof v === 'number' ? v : 0), 0);
} else {
count = Number(rawResult) || 0;
}
return count;
}
} catch {}
}
// Fallback to tiktoken — 04.10 ABORT-CONTRACT arc item (c): bounded sync encode, same idiom as the countTokens()
// message loop above. System prompts can be large (serialized tool definitions ride in them) — an unbounded BPE
// here would block the host event loop for seconds. ≤ cap → byte-identical result as before; overflow beyond it
// is estimated with the SAME ratio as the primary heuristic path (shared agentic density via estimateTokensFromChars - see tokenStatsManager), so no under-count that
// could delay compression. Callers today treat this number as a reserved/future-use value, but the WORK still ran.
if (!this.encoder) this.encoder = get_encoding('cl100k_base');
const structuredText = `<|start|>system<|end|>\n${text}`;
const encodable = structuredText.length <= TIKTOKEN_SYNC_ENCODE_CHAR_CAP
? structuredText
: structuredText.slice(0, TIKTOKEN_SYNC_ENCODE_CHAR_CAP);
let tokenCount = this.encoder.encode(encodable).length;
if (structuredText.length > TIKTOKEN_SYNC_ENCODE_CHAR_CAP) {
const overflowChars = structuredText.length - TIKTOKEN_SYNC_ENCODE_CHAR_CAP;
const estimatedOverflowTokens = estimateTokensFromChars(overflowChars);
tokenCount += estimatedOverflowTokens;
console.log(`[ContextGuard] ⚠️ Tiktoken fallback (_countStringTokens): system prompt exceeded ${TIKTOKEN_SYNC_ENCODE_CHAR_CAP.toLocaleString('en-US')} chars — encoded cap precisely, +${estimatedOverflowTokens.toLocaleString('en-US')} tokens estimated for the overflow (shared agentic density - see tokenStatsManager) to keep the sync encode bounded.`);
}
return tokenCount + 8; // +8 for overhead/BOS
}
// 📊 Percent-based trigger (07.10) — mirrors compressHistory() so external consumers (preprocessor,
// AutoTracker gates) always agree with the internal compression decision.
getThreshold(): number {
return this.config.tokenLimit * (this.config.compressionPercent / 100);
}
/**
* Resets the token cache when history changes.
*/
resetTokenCache() {
this.cachedTokenCount = null;
}
/**
* Gets the current token budget information as a human-readable string.
*/
getTokenBudgetInfo(): string {
const current = this.cachedTokenCount ?? 0;
const limit = this.config.tokenLimit;
const percentage = Math.round((current / limit) * 100);
return `[ContextGuard] Budget: ${Math.round(current / 1000)}k/${Math.round(limit / 1000)}k tokens (${percentage}% used)`;
}
/**
* Gets the configured token limit.
*/
getTokenLimit(): number {
return this.config.tokenLimit;
}
/**
* Receives prediction stats from LM Studio's inference engine.
* This replaces estimation with actual token counts from PredictionResult.stats,
* matching exactly what LM Studio's sidebar displays.
*
* Call this after awaiting on model.respond() or model.complete().result()
* to update the cached token count with authoritative SDK data.
*
* DORMANT WIRING (FIX #20, 23.08): no caller in src/ — this path is only fed by a registered
* prediction-loop handler / model.respond() consumer. LM Studio Core REJECTS plugins that register
* BOTH a tools provider and a predictionLoopHandler ("Tools provider cannot be used with a
* predictionLoopHandler" — boot crash verified 21.08; SDK v1.5.0 was latest as of 22.08, no upgrade
* path). ai_toolbox is a tools plugin, so this hook stays inactive by design until core changes.
* The mid-loop gap it would have closed is now covered by TokenStatsManager A1 delta bookkeeping +
* AutoTracker.guardMidLoopThreshold (see future_improvements/autoTracker_midloop_fix_plan.md).
*
* @param stats - LLMPredictionStats from PredictionResult.stats
*/
receivePredictionStats(stats: LLMPredictionStats): void {
// Update the TokenStatsManager so other components can access it
TokenStatsManager.updateFromPredictionResult(stats);
// Also update our cached count if totalTokensCount is available
if (stats.totalTokensCount != null && stats.totalTokensCount > 0) {
this.cachedTokenCount = stats.totalTokensCount;
console.log(`[ContextGuard] ✅ Updated token count from LM Studio SDK: ${stats.totalTokensCount.toLocaleString('en-US')} tokens`);
// Log the full summary for debugging
const summary = TokenStatsManager.getSummary();
if (summary) {
debugLog('[ContextGuard]', summary);
}
} else {
console.warn(`[ContextGuard] ⚠️ Prediction stats received but totalTokensCount is invalid:`, stats);
}
}
/**
* Get the latest prediction summary from LM Studio's inference engine.
* Returns null if no predictions have been made yet.
*/
getPredictionStatsSummary(): string | null {
return TokenStatsManager.getSummary();
}
/**
* Updates the configuration dynamically.
*/
updateConfig(newConfig: Partial<ContextGuardConfig>): void {
this.config = { ...this.config, ...newConfig };
}
/**
* Sets or updates the LM Studio client reference for dynamic model queries.
*/
setLMClient(client: LMStudioClient | null): void {
this.lmClient = client;
}
/**
* Dynamically fetches and applies the actual context window length from the active LM Studio model.
*/
async setTokenLimitFromModel(modelId?: string): Promise<void> {
if (!this.lmClient) return; // Cannot query without client
try {
let model;
if (modelId && typeof modelId === 'string' && modelId.trim() !== '') {
// User provided explicit model ID — load it directly
console.log(`[ContextGuard] Loading specified model: ${modelId}`);
model = await this.getCachedModel(modelId);
} else {
// No model ID provided — use SDK's official pattern: call .model() without arguments
// This returns the currently loaded/active model (see LM Studio plugin examples)
debugLog('[ContextGuard] No explicit model ID. Using SDK auto-detection...');
try {
// Call .model() without arguments to get the currently active model
model = await this.lmClient.llm.model();
if (model) {
console.log(`[ContextGuard] ✅ Auto-detected active model via SDK`);
} else {
debugLog('[ContextGuard] No active model detected. Using default tokenLimit.');
}
} catch (err) {
debugLog(`[ContextGuard] Failed to detect active model: ${(err as Error).message}. Using default tokenLimit.`);
}
}
if (!model) {
// If auto-detection fails, keep the current effective window (last model-reported value or the built-in 30k startup fallback — see index.ts)
const configLimit = this.config.tokenLimit;
console.log(`[ContextGuard] ⚠️ Auto-detection failed. Using configured tokenLimit: ${configLimit}.`);
return; // Keep existing config.tokenLimit (which should come from plugin settings)
}
// ✅ Use SDK's native getContextLength() API (LM Studio TS v1.x+)
const typedModel = model as LLMModelWithOptionalMethods;
if (typeof typedModel.getContextLength === 'function') {
const actualContextLength = await typedModel.getContextLength();
if (actualContextLength > 0) {
this.config.tokenLimit = actualContextLength;
console.log(`[ContextGuard] ✅ Updated tokenLimit from SDK: ${actualContextLength}`);
} else {
const configLimit = this.config.tokenLimit;
console.warn(`[ContextGuard] getContextLength() returned ${actualContextLength}. Using configured limit: ${configLimit}`);
}
} else if (typedModel.config?.contextSize != null) {
// Fallback: read from model config if available
const fallbackLimit = typedModel.config.contextSize as number;
this.config.tokenLimit = fallbackLimit;
console.log(`[ContextGuard] ✅ Fetched contextSize from model config: ${fallbackLimit}`);
}
} catch (err) {
const configLimit = this.config.tokenLimit;
console.error(`[ContextGuard] Failed to fetch actual context length. Using configured limit: ${configLimit} (${(err as Error).message})`);
}
}
/**
* Gets the current cached token count (for external monitoring).
*/
getCurrentTokenCount(): number {
return this.cachedTokenCount ?? 0;
}
/**
* Smartly reads a file using Keyword-Grep for precision.
* FIX #3: Added max_length parameter to respect caller's truncation limits.
*/
smartRead(filePath: string, userPrompt?: string, maxLength?: number): string {
if (!this.config.smartReading) {
const content = readFileSync(filePath, 'utf-8');
return maxLength ? content.substring(0, maxLength) : content;
}
try {
const stats = statSync(filePath);
this.trackedFiles.set(filePath, { compressed: false, truncated: true, originalSize: stats.size });
const content = readFileSync(filePath, 'utf-8');
const lines = content.split('\n');
// FIX #3: Use caller's maxLength if provided, otherwise use defaults
const effectiveMaxLength = maxLength || 5000;
const maxLines = 2000;
const maxBytes = 100 * 1024;
// Return full content only if file is small AND within caller's limit
if (stats.size < maxBytes && lines.length < maxLines && content.length <= effectiveMaxLength) {
return content;
}
const keywords = this.extractKeywords(userPrompt || '');
let relevantLines: number[] = [];
if (keywords.length > 0) {
lines.forEach((line, index) => {
if (keywords.some(kw => line.toLowerCase().includes(kw.toLowerCase()))) {
relevantLines.push(index);
}
});
if (relevantLines.length > 0) {
const result = this.formatRelevantLines(lines, relevantLines);
// FIX #3: Truncate to maxLength even for smart-read results
return result.length > effectiveMaxLength
? result.substring(0, effectiveMaxLength) + `\n// [ContextGuard] Output truncated to ${effectiveMaxLength} chars`
: result;
}
}
// Fallback: header/footer view
const header = lines.slice(0, 50).join('\n');
const footer = lines.slice(-50).join('\n');
let fallbackResult = `// [ContextGuard] File truncated due to size (${stats.size} bytes)\n// --- HEADER (First 50 lines) ---\n${header}\n// --- FOOTER (Last 50 lines) ---\n${footer}\n// [ContextGuard] Content truncated for context efficiency.`;
// FIX #3: Respect maxLength on fallback too
if (fallbackResult.length > effectiveMaxLength) {
fallbackResult = fallbackResult.substring(0, effectiveMaxLength) + `\n// [ContextGuard] Output truncated to ${effectiveMaxLength} chars`;
}
return fallbackResult;
} catch (error) {
return `Error reading file: ${(error as Error).message}`;
}
}
/**
* Filters terminal output to prevent context bloat.
*/
filterTerminalOutput(output: string): string {
if (!this.config.terminalFilterEnabled) return output;
const threshold = this.config.terminalFilterLength || 2000;
if (output.length <= threshold) return output;
const lines = output.split('\n');
const head = lines.slice(0, 5).join('\n');
const tail = lines.slice(-5).join('\n');
return `${head}\n... [Output truncated: ${lines.length - 10} lines hidden] ...\n${tail}`;
}
/**
* Forces a fresh read of a tracked file (Re-RAG Trigger).
*/
reloadContextForFile(filePath: string): string {
if (this.trackedFiles.has(filePath)) {
this.trackedFiles.delete(filePath);
return `// [ContextGuard] Context reloaded for ${filePath}. Previous compression/truncation cleared.`;
}
return `// [ContextGuard] No tracked context for ${filePath}. Reading normally.`;
}
/**
* Compresses a specific file's tracked context (marks it as compressed).
*/
markFileAsCompressed(filePath: string): void {
if (this.trackedFiles.has(filePath)) {
const info = this.trackedFiles.get(filePath);
if (info) {
this.trackedFiles.set(filePath, { ...info, compressed: true });
}
} else {
// If not tracked yet, add it as compressed
try {
const stats = statSync(filePath);
this.trackedFiles.set(filePath, { compressed: true, truncated: false, originalSize: stats.size });
} catch {
console.error(`[ContextGuard] Cannot mark file as compressed - file not found: ${filePath}`);
}
}
}
/**
* Computes a simple hash of messages for cache invalidation.
* FIX #1: Ensures cache is invalidated when every message changes, not just the last one.
*/
private computeMessageHash(messages: ContextMessage[]): string {
return messages.map(m => {
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `${m.role}:${contentStr}`;
}).join('||');
}
/**
* Extracts meaningful keywords from a prompt for smart file reading.
*/
private extractKeywords(prompt: string): string[] {
const matches = prompt.match(/\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/g);
if (!matches) return [];
// Filter out stop words and keep only meaningful identifiers (length > 4)
return [...new Set(matches)]
.filter(w => w.length > 4 && !STOP_WORDS.has(w.toLowerCase()));
}
/**
* Formats relevant lines with context margins for smart reading.
*/
private formatRelevantLines(lines: string[], indices: number[]): string {
let result = '';
const margin = 5;
indices.forEach(index => {
const start = Math.max(0, index - margin);
const end = Math.min(lines.length, index + margin + 1);
result += `// ... [Match at line ${index + 1}] ... \n`;
result += lines.slice(start, end).join('\n') + '\n';
});
return result;
}
}
/**
* Hub-Exclusion Clustering Integration for ContextGuard
*
* Provides architectural transparency insights during context analysis:
* - Identifies which modules are hubs vs regular members
* - Tracks cluster membership for tracked files
* - Enables cluster-aware compression strategies
*/
import type { HubExclusionResult } from './utils/hubExclusionClustering.js';
import { analyzeAiToolboxDependencies } from './utils/hubExclusionClustering.js';
/**
* Cache for clustering analysis results (avoid recomputation).
*/
let cachedClusteringResult: HubExclusionResult | null = null;
let clusteringCacheTimestamp = 0;
/**
* Get or compute the Hub-Exclusion Clustering result.
* Cached for performance — invalidates after 5 minutes.
*/
function getClusteringResult(): HubExclusionResult {
const now = Date.now();
if (cachedClusteringResult && (now - clusteringCacheTimestamp) < 5 * 60 * 1000) {
return cachedClusteringResult;
}
cachedClusteringResult = analyzeAiToolboxDependencies();
clusteringCacheTimestamp = now;
debugLog('[CLUSTERING]', `Computed Hub-Exclusion Clustering: ${cachedClusteringResult.nodes.length} modules, ${cachedClusteringResult.clusters.length} clusters`);
return cachedClusteringResult;
}
/**
* Get the cluster membership for a given file/module path.
*/
export function getFileClusterInfo(filePath: string): {
isHub: boolean;
clusterId?: number;
moduleDegree: number;
clusterSize?: number;
clusterDensity?: number;
} | null {
const result = getClusteringResult();
// Normalize the file path to match node IDs in the clustering result
const normalizedPath = filePath.replace(/\\/g, '/').replace(/^.*\/src\//, '');
const matchingNode = result.nodes.find(n => n.id.includes(normalizedPath) || normalizedPath.includes(n.id));
if (!matchingNode) return null;
const isHub = result.hubs.includes(matchingNode.id);
let clusterId: number | undefined;
let clusterSize: number | undefined;
let clusterDensity: number | undefined;
// Find the cluster this node belongs to (or a hub's assigned cluster)
for (const cluster of result.clusters) {
if (cluster.members.includes(matchingNode.id)) {
clusterId = cluster.clusterId;
clusterSize = cluster.size;
clusterDensity = cluster.density;
break;
}
}
// If it's a hub, check its assignment
if (!clusterId && result.hubAssignments[matchingNode.id] != null) {
const assignedClusterId = result.hubAssignments[matchingNode.id];
if (assignedClusterId >= 0) {
clusterId = assignedClusterId;
const assignedCluster = result.clusters.find(c => c.clusterId === assignedClusterId);
clusterSize = assignedCluster?.size;
clusterDensity = assignedCluster?.density;
}
}
return {
isHub,
clusterId,
moduleDegree: matchingNode.degree,
clusterSize,
clusterDensity
};
}
/**
* Generate an architectural insight summary for the current context.
*
* Used during compression to provide users with insights about which
* modules are being affected and their roles in the architecture.
*/
export function getArchitecturalInsights(): string {
const result = getClusteringResult();
let insights = '\n🏗️ Architectural Context Summary\n';
insights += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
// Module distribution
insights += `Modules analyzed: ${result.nodes.length}\n`;
insights += `Clusters identified: ${result.clusters.length}\n`;
insights += `Hub modules: ${result.hubs.length}\n\n`;
// Hub roles
if (result.hubs.length > 0) {
insights += '🔶 Architectural Hubs:\n';
for (const hubId of result.hubs.slice(0, 5)) {
const node = result.nodes.find(n => n.id === hubId);
if (node) {
insights += ` • ${node.label || hubId} — connects ${node.degree} modules\n`;
}
}
if (result.hubs.length > 5) {
insights += ` ... and ${result.hubs.length - 5} more hubs\n`;
}
insights += '\n';
}
// Cluster summary
insights += '📦 Module Clusters:\n';
for (const cluster of result.clusters.slice(0, 3)) {
const densityStr = cluster.density != null ? ` | density: ${cluster.density.toFixed(2)}` : '';
insights += ` Cluster ${cluster.clusterId}: ${cluster.size} modules${densityStr}\n`;
// Show representative members
for (const member of cluster.members.slice(0, 3)) {
const node = result.nodes.find(n => n.id === member);
if (node) {
insights += ` • ${node.label || member}\n`;
}
}
}
// Modularity quality
if (result.modularity != null) {
const quality = result.modularity > 0.3 ? 'Strong' : result.modularity > 0.2 ? 'Moderate' : 'Weak';
insights += `\n📊 Clustering quality: ${quality} (${result.modularity.toFixed(3)})\n`;
}
return insights;
}
/**
* Check if a file belongs to a hub module — useful for compression priority.
* Hub modules should be preserved during context compression as they are
* architecturally critical.
*/
export function isHubModule(filePath: string): boolean {
const info = getFileClusterInfo(filePath);
return info?.isHub ?? false;
}
/**
* Get the cluster ID for a file — useful for cluster-aware compression strategies.
* Files in the same cluster can be compressed together to reduce redundancy.
*/
export function getModuleClusterId(filePath: string): number | null {
const info = getFileClusterInfo(filePath);
return info?.clusterId ?? null;
}
/**
* Compress files from the same cluster together (optimization).
*
* When multiple tracked files belong to the same cluster, they can be
* compressed in a single operation rather than individually.
*/
export function groupTrackedFilesByCluster(trackedPaths: string[]): Map<number, string[]> {
const clusters = new Map<number, string[]>();
for (const filePath of trackedPaths) {
const clusterId = getModuleClusterId(filePath);
if (clusterId != null && clusterId >= 0) {
if (!clusters.has(clusterId)) {
clusters.set(clusterId, []);
}
clusters.get(clusterId)!.push(filePath);
} else {
// Files not in any cluster or hubs go to a special group
const unclustered = clusters.get(-1);
if (!unclustered) {
clusters.set(-1, [filePath]);
} else {
unclustered.push(filePath);
}
}
}
return clusters;
}
/**
* ContextGuard Module (Optimized for Speed & Precision)
* Implements Summarization, Smart Reading, and Re-RAG tracking.
*/
/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-non-null-assertion */
// The above disables are required because the LM Studio SDK (@lmstudio/sdk v1.5.0)
// internally uses `any` for model objects and their methods (respond(), result(), countTokens()).
// This propagates through our code when interacting with SDK types. Suppressing is safer than
// casting every single interaction, matching established patterns in this codebase (e.g., refactorCodeTools.ts).
import { get_encoding } from '@dqbd/tiktoken';
import type { Tiktoken } from '@dqbd/tiktoken';
import { readFileSync, statSync } from 'fs';
// 🔹 P1 Optimization #2: JSON serialization cache to avoid redundant stringify() calls in loops
const jsonCache = new WeakMap<object, string>();
function cachedJSONStringify(obj: unknown): string {
if (typeof obj === 'string') return obj;
const cacheKey = typeof obj === 'object' && obj !== null ? obj : null;
if (cacheKey) {
let cached = jsonCache.get(cacheKey);
if (!cached) {
cached = JSON.stringify(obj);
jsonCache.set(cacheKey, cached);
}
return cached;
}
return String(obj);
}
import type { LMStudioClient, LLMPredictionStats } from '@lmstudio/sdk';
import { TokenStatsManager, estimateTokensFromChars } from './tokenStatsManager.js';
// Arc C (07.10): structured continuity generation at the compression trigger — parser + persist live in
// sessionSummaryPersist.ts; cycle-free by construction (toolsProvider / all src/tools modules never import
// contextGuard or promptPreprocessor, only index.ts imports both sides of that graph). FIX B (09.10) reuses BOTH
// exports here for the mid-loop forced-compression pipeline — grep-verified 09.10: no runtime edge back into
// contextGuard from any module these chain through (only index.ts imports contextGuard at runtime; promptPreprocessor's
// is type-only).
import type { SessionSummaryData } from './tools/contextManagementTools.js';
import { hasMeaningfulUserContent, parseSessionContinuity, persistGeneratedSessionSummary, stripSummaryArtifacts } from './sessionSummaryPersist.js';
// FIX B (09.10): PART-B pipeline parity for compressMidLoop() — pre-summarization payload pruning + the canonical
// AutoTracker checkpoint snapshot (PART B). No import cycle: autoTracker imports only zod (+ a deferred dynamic
// import of tools/contextManagementTools.js, which never references contextGuard); workingDir is dependency-free.
import { autoTracker } from './autoTracker.js';
import { getWorkingDir } from './workingDir.js';
// FIX B (09.10): C compaction family — same store-before-prune ordering and byte budget as PART B in promptPreprocessor.
import { DEFAULT_MAX_BYTES_PER_RESULT, pruneOversizedToolPayloads } from './utils/toolPayloadCompaction.js';
import { collectPrunedPayloadRefs, storePrunedPayload } from './utils/toolPayloadStorage.js';
// Common English words to exclude from keyword extraction (false positives)
const STOP_WORDS = new Set([
'about', 'above', 'after', 'again', 'against', 'all', 'am', 'an', 'and', 'any',
'are', "aren't", 'as', 'at', 'be', 'because', 'been', 'before', 'being', 'below',
'between', 'both', 'but', 'by', 'can', "couldn't", 'could', 'did', "didn't", 'do',
'does', 'doing', 'don\'t', 'down', 'during', 'each', 'few', 'for', 'from', 'further',
'get', 'got', 'had', "hadn't", 'has', "hasn't", 'have', "haven't", 'having', 'he',
'her', 'here', 'hers', 'herself', 'him', 'himself', 'his', 'how', 'i', 'if', 'in',
'into', 'is', "isn't", 'it', "it's", 'its', 'itself', 'just', 'let', 'me', 'might',
'more', 'most', "mustn't", 'my', 'myself', 'new', 'no', 'nor', 'not', 'now', 'of',
'off', 'on', 'once', 'only', 'or', 'other', 'our', 'ours', 'out', 'over', 'own',
'same', "shan't", 'she', "she's", 'should', "shouldn't", 'so', 'some', 'such',
'than', 'that', "that'll", 'the', 'their', 'theirs', 'them', 'themselves', 'then',
'there', 'these', 'they', 'this', 'those', 'through', 'to', 'too', 'under',
'until', 'up', 'very', 'was', "wasn't", 'we', 'were', "weren't", 'what', 'when',
'where', 'which', 'while', 'who', 'whom', 'why', 'will', 'with', "won't", 'would',
"wouldn't", 'you', "you'd", "you'll", "you're", "you've", 'your', 'yours',
'yourself', 'yourselves', 'able', 'also', 'back', 'come', 'could', 'day', 'even',
'give', 'good', 'know', 'last', 'long', 'look', 'make', 'many', 'may', 'much',
'need', 'next', 'part', 'put', 'say', 'see', 'show', 'take', 'time', 'use',
'want', 'way', 'work', 'year', 'yes', 'yet', 'you',
// Technical false positives
'function', 'variable', 'context', 'guard', 'config', 'module', 'class', 'const',
'let', 'var', 'async', 'await', 'return', 'throw', 'catch', 'try', 'finally',
'import', 'export', 'default', 'from', 'type', 'interface', 'enum', 'implements',
'extends', 'super', 'this', 'new', 'delete', 'typeof', 'instanceof', 'void',
]);
// 🔹 P1 Optimization #3: Conditional logging to reduce stderr I/O in production
const DEBUG_MODE = !!process.env.AI_TOOLBOX_DEBUG;
/**
* Calibration factor — MUST stay 1 (no scaling).
*
* History: was once set to 65, derived from a single observation
* ("Real Usage ~184k at 81% / Plugin Count ~2616 ≈ 70x"). That gap was NOT tokenizer drift:
* the sidebar counts the FULL request (chat history + ALL serialized tool definitions
* + chat template), while that measurement only counted a small message fragment.
* Multiplying real token counts by 65 inflated every SDK/tiktoken-based estimate ~65×
* (e.g., a normal conversation read as "412k tokens"), which triggered premature
* compression, wrong AutoTracker warnings and misleading logs.
*/
const TOKEN_SCALING_FACTOR = 1;
/**
* Hard wall-clock cap (ms) for the internal summarization prediction in compressHistory()
* (model.respond, maxTokens=1024). Without it a slow/under-resourced summary model could block
* prompt preprocessing indefinitely. 60s covers realistic local-model runs of ≤1024 tokens while
* bounding worst-case latency. Kept here (single consumer) rather than in utils/grepGuard.ts,
* whose caps are scoped to the file-scan tools.
*/
const COMPRESSION_PREDICTION_MAX_MS = 60_000;
// 04.10 ABORT-CONTRACT arc item (c): hard per-message cap for the SYNCHRONOUS tiktoken fallback encode in
// countTokens(). Tiktoken's encoder.encode() is CPU-bound sync work — a multi-MB message content would block the
// plugin host event loop for seconds (UI stall / watchdog). Messages are encoded precisely up to this budget, and any
// overflow beyond it is estimated via estimateTokensFromChars() — the shared agentic-density ratio in tokenStatsManager, so a
// single oversized message cannot both block the loop AND drive an under-count that delays compression. Typical
// chat/file-paste messages are ≤ ~50k chars → for them this changes NOTHING (cap is never reached).
const TIKTOKEN_SYNC_ENCODE_CHAR_CAP = 100_000;
/**
* Composes an optional external (host/preprocessor) AbortSignal with a hard wall-clock cap into ONE
* AbortSignal for SDK prediction opts — same one-controller pattern as utils/grepGuard.ts: the host
* signal is forwarded via listener (per WHATWG spec signals are one-way, no reverse .abort()), and
* exactly one timer arms the cap. Returns { signal, dispose }; dispose() MUST be called on every
* completion path so no stray timer or listener survives after the prediction settles.
*/
function withTimeoutCap(external: AbortSignal | undefined, maxMs: number): { signal: AbortSignal; dispose: () => void } {
const controller = new AbortController();
let forwardAbort: (() => void) | undefined;
if (external) {
if (external.aborted) {
controller.abort();
} else {
forwardAbort = () => controller.abort();
external.addEventListener('abort', forwardAbort, { once: true });
}
}
let deadlineId: ReturnType<typeof setTimeout> | undefined;
if (maxMs > 0) {
deadlineId = setTimeout(() => {
console.warn(`[ContextGuard] compression prediction cap (${maxMs}ms) reached — aborting, using fallback summary`);
controller.abort();
}, maxMs);
}
return {
signal: controller.signal,
dispose(): void {
if (deadlineId !== undefined) clearTimeout(deadlineId);
if (external && forwardAbort) external.removeEventListener('abort', forwardAbort);
},
};
}
function debugLog(...args: unknown[]): void {
if (DEBUG_MODE) console.log('[ContextGuard]', ...args);
}
export interface ContextGuardConfig {
tokenLimit: number; // effective context window (absolute tokens) — model-reported or built-in fallback
compressionPercent: number; // 📊 Compression trigger as % of tokenLimit (07.10: replaces the hardcoded *0.9 / absolute menu limit), default 90
smartReading: boolean;
summaryModel: string;
terminalFilterEnabled: boolean;
terminalFilterLength: number;
}
/** Message type for context guard operations */
type ContextMessage = {
role?: string;
content?: unknown;
[key: string]: unknown;
};
/** Minimal interface for LM Studio model objects with optional SDK methods */
interface LLMModelWithOptionalMethods {
getContextLength?(): Promise<number>;
config?: Record<string, unknown>;
}
export class ContextGuard {
private encoder: Tiktoken | null = null;
private config: ContextGuardConfig;
private lmClient: LMStudioClient | null = null;
private cachedTokenCount: number | null = null;
private _lastMessageHash: string | null = null; // FIX #1: Hash-based cache invalidation
private trackedFiles: Map<string, { compressed: boolean; truncated: boolean; originalSize: number }> = new Map();
// 🔹 P2 Optimization #4: Cache model reference to avoid repeated IPC calls
private cachedModelRef: any = null;
private cachedModelId: string | null = null;
// 🔹 Optional callback invoked when compression occurs (for coordinating with AutoTracker)
onCompression?: () => void;
constructor(config: ContextGuardConfig, lmClient: LMStudioClient | null = null) {
this.config = config;
this.lmClient = lmClient;
}
/** 🔹 P2 #4: Get or create a cached model reference */
private async getCachedModel(modelId: string): Promise<any> {
if (this.cachedModelId === modelId && this.cachedModelRef) return this.cachedModelRef;
const model = await this.lmClient!.llm.model(modelId);
this.cachedModelRef = model;
this.cachedModelId = modelId;
return model;
}
/**
* Counts tokens efficiently with caching.
* Uses the shared agentic-density estimate (estimateTokensFromChars, tokenStatsManager) → SDK native counting → Tiktoken estimation.
*
* 🔥 PRIORITY ORDER:
* 1. Shared agentic-density estimate (chars ÷ measured 3.2 c/tok, recalibrated 10.11 — see tokenStatsManager for provenance)
* 2. SDK PredictionResult.stats — From model.respond().result().stats
* 3. SDK native countTokens() — Model-specific tokenization
* 4. Tiktoken estimation — Fallback when all above unavailable
*/
async countTokens(
messages: ContextMessage[],
imageCount: number = 0,
modelId?: string,
systemPrompt?: string,
historyTextLength?: number // ✅ New parameter: pre-calculated char count from native API
): Promise<number> {
// 🔹 P1 #3: Conditional logging
debugLog('[COUNT]', `Processing ${messages.length} messages.`);
// ✅ PRIMARY METHOD: If historyTextLength is provided (from native API), use the shared agentic-density
// ratio from tokenStatsManager — recalibrated to the MEASURED content density in 10.11 (TOKEN-DIVERGENCE arc;
// provenance + band-floor rationale live at the single source of truth there). Avoids SDK overestimation (~124k vs ~80k)
if (historyTextLength != null && historyTextLength > 0) {
const primaryTokenCount = estimateTokensFromChars(historyTextLength); // shared ratio — see tokenStatsManager
// Add image tokens if applicable (SDK doesn't account for multi-modal images automatically)
let totalTokens = primaryTokenCount;
if (imageCount > 0) {
totalTokens += imageCount * 500; // Conservative estimate per LM Studio convention
}
this.cachedTokenCount = totalTokens;
this._lastMessageHash = this.computeMessageHash(messages);
console.log(`[ContextGuard] ✅ Primary count: ${historyTextLength.toLocaleString('en-US')} chars → ${primaryTokenCount.toLocaleString('en-US')} tokens (shared agentic-density ratio — see tokenStatsManager)`);
return totalTokens;
}
// Count System Prompt tokens if provided (reserved for future use)
/* eslint-disable @typescript-eslint/no-unused-vars */
const _accumulatedTokens = systemPrompt ? await this._countStringTokens(systemPrompt, modelId) : 0;
/* eslint-enable @typescript-eslint/no-unused-vars */
// 🔥 FALLBACK: Use SDK-native countTokens() on the FULL message array.
// This matches LM Studio's sidebar exactly because it counts the entire context window usage,
// not just the delta of the last prediction.
if (this.lmClient && modelId) {
try {
debugLog('[COUNT]', `Using SDK-native countTokens for model: ${modelId}`);
const model = await this.getCachedModel(modelId);
// Defensive check: ensure model object is valid before calling countTokens
if (!model || typeof model.countTokens !== 'function') {
debugLog('[COUNT]', 'Model or countTokens not available, falling back to manual encoding');
throw new Error('Model or countTokens method not available');
}
// ✅ FIX #3: Serialize ALL message fields (including tool_calls, files) into the tokenization string.
// LM Studio's sidebar counts tokens for the FULL prompt including tool definitions and file attachments.
// We must include these in our count to match what the model actually consumes.
const promptString = messages.map(m => {
const role = m.role || 'user';
let contentStr: string;
// Extract actual text content from various message formats (SDK v1.x compatibility)
if (typeof m.content === 'string') {
contentStr = m.content;
} else if (Array.isArray(m.content)) {
// Handle array of content blocks (e.g., [{"type": "text", "text": "..."}])
contentStr = (m.content as Array<Record<string, unknown>>).map(block => {
const textVal = typeof block.text === 'string' ? block.text : '';
return textVal;
}).join('\n');
} else if (typeof m.content === 'object' && m.content !== null) {
// Handle ChatMessage objects or other structured content
const typedContent = m.content as Record<string, unknown>;
// Try .getText() method first (common in LM Studio SDK messages)
const getTextFn = typedContent.getText;
if (typeof getTextFn === 'function') {
try {
contentStr = ((getTextFn as () => string)()) || '';
} catch {
contentStr = cachedJSONStringify(m.content);
}
} else if (typeof typedContent.text === 'string') {
contentStr = typedContent.text;
} else if (typedContent.text != null && typeof typedContent.text !== 'object') {
// eslint-disable-next-line @typescript-eslint/no-base-to-string
contentStr = String(typedContent.text);
} else {
contentStr = cachedJSONStringify(m.content);
}
} else {
contentStr = '';
}
// Extract and serialize additional fields that contribute to token count
const typedMsg = m as Record<string, unknown>;
let extras: string[] = [];
// ⚠️ Tool calls are DELIBERATELY NOT serialized into the SDK countTokens() prompt.
// @lmstudio/sdk (v1.8.x) LLM.countTokens() throws ToolCallRequestError when the input
// contains tool-call structures ("Cannot count tokens for messages that contain tool
// calls"). The existing try/catch below falls back to tiktoken on that error, but it is
// better not to trigger it in the first place. Cost of omitted tool-call text is covered:
// the preprocessor's primary heuristic (estimateTokensFromChars over historyTextLength — shared agentic-density ratio) already includes
// full getToolCallRequests()/getToolCallResults() payloads via the native history API, and
// this fallback only runs when that primary path was unavailable for this turn.
// Files / attachments
const files = typedMsg.files || typedMsg.images;
if (files && Array.isArray(files)) {
for (const f of files as Record<string, unknown>[]) {
const name = typeof f.name === 'string' ? f.name : 'unknown';
extras.push(`[FILE: ${name}]`);
}
}
// Combine role prefix with content and all extra fields
const fullBlock = `<|start|>${role}<|end|>\n${contentStr}${extras.join('\n')}`;
return fullBlock;
}).join('\n\n');
let rawResult: unknown = await model.countTokens(promptString);
// Defensive handling for SDK response structure variations
// The SDK might return { data: number } or similar wrapper object
if (typeof rawResult === 'object' && rawResult !== null) {
const objResult = rawResult as Record<string, unknown>;
// Check if result has a .data property (common in newer SDK versions)
if ('data' in objResult && typeof objResult.data !== 'undefined') {
rawResult = objResult.data;
} else if ('value' in objResult && typeof objResult.value !== 'undefined') {
// Some SDKs use .value instead
rawResult = objResult.value;
} else {
debugLog('[COUNT]', 'Unexpected SDK response structure, falling back to manual encoding');
throw new Error('Unexpected response structure: no data/value property found');
}
}
// Now process the result (which should be a number or array)
let sdkCount: number;
if (Array.isArray(rawResult)) {
const numArray = rawResult as unknown[];
sdkCount = numArray.reduce((sum: number, val: unknown) => sum + (typeof val === 'number' ? val : 0), 0);
} else if (typeof rawResult === 'number') {
sdkCount = rawResult;
} else {
debugLog('[COUNT]', `Unexpected result type: ${typeof rawResult}, falling back to manual encoding`);
throw new Error(`Unexpected result type: ${typeof rawResult}`);
}
// Add image token estimation (SDK doesn't always account for multi-modal images automatically)
let totalTokens = sdkCount;
if (imageCount > 0) {
const imageTokens = imageCount * 500; // Conservative estimate per LM Studio convention
totalTokens += imageTokens;
debugLog('[COUNT]', `Adding ${imageTokens} tokens for ${imageCount} images.`);
}
// Apply calibration factor to account for LM Studio sidebar overhead (tool defs, BOS/EOS, chat templates)
const calibratedTotal = Math.round(totalTokens * TOKEN_SCALING_FACTOR);
this.cachedTokenCount = calibratedTotal;
this._lastMessageHash = this.computeMessageHash(messages);
console.log(`[ContextGuard] ✅ SDK count: ${totalTokens.toLocaleString('en-US')} tokens (Calibrated: ${calibratedTotal.toLocaleString('en-US')})`);
return calibratedTotal;
} catch (error) {
const errorMsg = error instanceof Error ? error.message : String(error);
console.log(`[ContextGuard] SDK token counting failed for "${modelId}", falling back to manual encoding. Reason: ${errorMsg}` +
` (known causes: model not loaded / countTokens unavailable, or ToolCallRequestError when the prompt contains tool-call structures)`);
// Fall through to manual tiktoken below
}
}
// Fallback: Manual Tiktoken encoding (preserves backward compatibility)
if (!this.encoder) {
this.encoder = get_encoding('cl100k_base');
}
let count = 0;
for (const msg of messages) {
const role = msg.role || 'user';
// Try to get content string, fallback to getText() if content is empty
let contentStr: string = '';
if (typeof msg.content === 'string') {
contentStr = msg.content;
} else if (msg.content != null && typeof msg.content !== 'string') {
contentStr = JSON.stringify(msg.content);
} else {
// Fallback for ChatMessage objects with empty content
const typedMsg = msg as Record<string, unknown>;
const getTextFn = typedMsg.getText;
if (typeof getTextFn === 'function') {
try {
contentStr = ((getTextFn as unknown as () => string)()) || '';
} catch (e) {
debugLog('[COUNT]', `getText() failed: ${(e as Error).message}`);
contentStr = '';
}
}
}
// 🔹 P1 #3: Conditional logging for debugging message integrity
debugLog('[COUNT]', `Message content length: ${contentStr.length} chars (role: ${role})`);
// Account for message structure: role prefix + separator + content
// This matches how LLMs actually consume tokens in chat completion API
const structuredText = `<|start|>assistant<|name|>${role}<|end|>\n${contentStr}`;
// 04.10 ABORT-CONTRACT arc item (c): bounded sync encode — precise BPE up to TIKTOKEN_SYNC_ENCODE_CHAR_CAP,
// overflow estimated via estimateTokensFromChars() (shared agentic-density ratio in tokenStatsManager). ≤ cap → exact encode only, as before.
const encodable = structuredText.length <= TIKTOKEN_SYNC_ENCODE_CHAR_CAP
? structuredText
: structuredText.slice(0, TIKTOKEN_SYNC_ENCODE_CHAR_CAP);
count += this.encoder.encode(encodable).length;
if (structuredText.length > TIKTOKEN_SYNC_ENCODE_CHAR_CAP) {
const overflowChars = structuredText.length - TIKTOKEN_SYNC_ENCODE_CHAR_CAP;
const estimatedOverflowTokens = estimateTokensFromChars(overflowChars);
count += estimatedOverflowTokens;
console.log(`[ContextGuard] ⚠️ Tiktoken fallback: message (${role}) exceeded ${TIKTOKEN_SYNC_ENCODE_CHAR_CAP.toLocaleString('en-US')} chars — encoded cap precisely, +${estimatedOverflowTokens.toLocaleString('en-US')} tokens estimated for the overflow (shared agentic density - see tokenStatsManager) to keep the sync encode bounded.`);
}
}
// Add estimated tokens for images (LM Studio uses ~500-1000 tokens per image)
if (imageCount > 0) {
const imageTokens = imageCount * 500; // Conservative estimate
count += imageTokens;
debugLog('[COUNT]', `Adding ${imageTokens} tokens for ${imageCount} images.`);
}
// Add a small overhead for system prompt and BOS token (typically ~4-8 tokens)
count += 8;
// Apply calibration factor to match LM Studio sidebar
const calibratedCount = Math.round(count * TOKEN_SCALING_FACTOR);
this.cachedTokenCount = calibratedCount;
this._lastMessageHash = this.computeMessageHash(messages); // FIX #1: Store hash
debugLog('[COUNT]', `Tiktoken count: ${count.toLocaleString('en-US')} tokens (Calibrated: ${calibratedCount.toLocaleString('en-US')})`);
return calibratedCount;
}
/**
* Tracks whether compression was performed in the last operation.
*/
private _lastCompressionInfo: {
compressed: boolean;
originalTokens?: number;
compressedTokens?: number;
messagesCompressed?: number;
timestamp?: Date;
} | null = null;
/**
* Gets information about the last compression operation.
*/
getLastCompressionInfo(): typeof this._lastCompressionInfo {
return this._lastCompressionInfo;
}
/**
* Compresses history by sending oldest messages to a local model.
*
* @param abortSignal optional host/preprocessor AbortSignal (SDK ctl.abortSignal) — when aborted,
* the in-flight summarization prediction stops immediately and the documented fallback summary is
* used instead. Independently of this signal, the prediction is hard-capped at
* COMPRESSION_PREDICTION_MAX_MS so a slow summary model can never block preprocessing forever.
* @param trustedTokenCount B1 (29.10, owner GO — dual-counter divergence fix): authoritative token
* count computed by the CALLER with the SAME shared agentic-density estimator that armed this call
* (only compressMidLoop passes it today — its wrapper projection). When present and > 0 it is used
* VERBATIM for the threshold decision: one counter, one text set, one live density → the "gate fired
* but internal recount vetoed" divergence of 29.10 (projection ~141.9k ≥ 95% gate while an independent
* SDK/tiktoken recount sat below the 90% trigger) becomes arithmetically impossible on this path.
* Absent/invalid → legacy behavior byte-for-byte: countTokens() re-counts (PART B boundary calls and
* every external consumer are untouched).
*/
async compressHistory(
messages: ContextMessage[],
abortSignal?: AbortSignal,
trustedTokenCount?: number,
): Promise<ContextMessage[]> {
// B1 (29.10) — single-counter contract: when the caller supplies its authoritative shared-density count
// (only compressMidLoop does today), it IS this decision's count and NO independent recount runs at all
// (saves an SDK/tiktoken pass over the full history mid-loop and removes that path's throw surface from
// the tool-call loop). It feeds THIS threshold check only — never display figures or any other path.
let currentTokens: number;
if (trustedTokenCount != null && Number.isFinite(trustedTokenCount) && trustedTokenCount > 0) {
currentTokens = Math.round(trustedTokenCount);
console.log(`[ContextGuard] [B1] Using caller-provided shared-density count ${currentTokens.toLocaleString('en-US')} for the compression decision (single-counter contract; independent recount suppressed)`);
} else {
// 🔹 FIX #2 (legacy path, byte-for-byte pre-B1): Pass summaryModel to countTokens so SDK-native counting is used during threshold check.
currentTokens = await this.countTokens(messages, 0, this.config.summaryModel);
}
// 📊 Percent-based trigger (07.10): compression at `compressionPercent` % of the effective window
// (default 90% — numerically identical to the former hardcoded *0.9).
const threshold = this.config.tokenLimit * (this.config.compressionPercent / 100);
if (currentTokens < threshold) {
debugLog('[COMPRESS]', `Token count (${currentTokens}) below threshold (${threshold}). No compression needed.`);
this._lastCompressionInfo = { compressed: false };
return messages;
}
const originalTokenCount = currentTokens;
// Reset token counter and notify user as requested when context limit is exceeded
debugLog('[COMPRESS]', `Compressing history: ${messages.length} messages, ${currentTokens} tokens (threshold: ${threshold})`);
// Notify user in chat via system prompt instead of stderr logging
// FIX-1B (29.10, owner GO — truthfulness): the old text claimed "Token counter reset", which never happened for the
// request actually sent: pullHistory() is an immutable-to-plugins COPY (SDK contract), so host history keeps riding
// every payload even after compression (29.10 incident: 167k-token rejection immediately after a "successful"
// compression). State the real limitation instead of a phantom reset — verified unfixable via any plugin API version.
const thresholdWarning = `⚠️ Context window threshold reached (${originalTokenCount.toLocaleString('en-US')} tokens). Note: in-chat compression cannot shrink the history LM Studio sends (plugin-API limitation) — please start a completely new session to reset context.`;
console.log(`[ContextGuard] ${thresholdWarning}`);
const keepLast = 10;
const toCompress = messages.slice(0, -keepLast);
if (toCompress.length === 0) {
debugLog('[COMPRESS]', `No messages to compress (only ${messages.length} total, keeping last ${keepLast})`);
return messages;
}
// Inject warning into chat history as a persistent system message (visible to LLM)
const chatWarningMessage = {
role: 'system' as const,
content: `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`⚠️ **CONTEXT WINDOW THRESHOLD REACHED** ⚠️\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`${thresholdWarning}\n\n` +
`### ACTION TAKEN:\n` +
`- Oldest ${toCompress.length} message(s) have been compressed into a summary below.\n` +
`- Token counter has been reset to zero.\n` +
`- Please start a completely new session for optimal performance.\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY (compressed from ${toCompress.length} messages)\n`
};
// Use local model for summarization
if (this.lmClient && this.config.summaryModel) {
try {
debugLog('[COMPRESS]', `Loading model: ${this.config.summaryModel}`);
const model = await this.getCachedModel(this.config.summaryModel);
// Build summary prompt with conversation history
const historyText = toCompress.map(m => {
const role = (m.role || 'user').toUpperCase();
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `[${role}] ${contentStr}`;
}).join('\n\n');
const summaryPrompt = `You are an intelligent context compressor. Summarize the following conversation history into a concise technical summary.
INSTRUCTIONS:
1. Preserve ALL file paths, function names, class names, and variable names exactly as written
2. Keep key logic descriptions and architectural decisions
3. Discard verbose code blocks — describe them instead
4. Remove terminal noise, progress indicators, and repetitive output
5. Maintain chronological flow of the conversation
6. Be precise but brief (max 500 words)
CONVERSATION HISTORY TO SUMMARIZE:
${historyText}
SUMMARY:`;
debugLog('[COMPRESS]', `Sending summarization request for ${toCompress.length} messages...`);
// Use respond() for chat-based interaction (more reliable than complete()).
// Cancellable + capped: host abort signal forwarded in AND hard wall-clock cap — see withTimeoutCap().
const { signal: predictionSignal, dispose: disposePredictionGuard } = withTimeoutCap(abortSignal, COMPRESSION_PREDICTION_MAX_MS);
try {
const response = model.respond(
[{ role: 'user', content: summaryPrompt }],
{ maxTokens: 1024, temperature: 0.1, signal: predictionSignal }
);
// Wait for the result — prediction runs here; host cancel or cap aborts it in-flight.
const result = await response.result();
// User cancel (host abort) or cap timeout → SDK reports stopReason 'userStopped'. Treat as a failed
// compression and take the documented fallback path below instead of trusting partial content.
if (result.stats && result.stats.stopReason === 'userStopped') {
throw new Error('Summarization stopped by user cancel or prediction cap');
}
const summary = result.content || `[ContextGuard Summary: ${toCompress.length} older messages compressed.]`;
debugLog('[COMPRESS]', `Summarization complete. Generated ${summary.length} chars.`);
// Count tokens after compression using SDK-native method
const compressedPreview = [
{ role: 'system', content: `### CONTEXT SUMMARY (compressed from ${toCompress.length} messages)\n${summary}` },
...messages.slice(-keepLast)
];
const compressedTokenCount = await this.countTokens(compressedPreview, 0, this.config.summaryModel);
// Track compression info
this._lastCompressionInfo = {
compressed: true,
originalTokens: originalTokenCount,
compressedTokens: compressedTokenCount,
messagesCompressed: toCompress.length,
timestamp: new Date()
};
// 🔹 Notify listeners (e.g., AutoTracker) that compression occurred
if (this.onCompression) {
this.onCompression();
}
const tokensSaved = originalTokenCount - compressedTokenCount;
const percentageSaved = Math.round((tokensSaved / originalTokenCount) * 100);
// Visual indicator message
const visualIndicator = {
role: 'system' as const,
content: `🧠 **ContextGuard Compression Active**\n\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`• Compressed ${toCompress.length} message(s) into summary\n` +
`• Tokens before: ~${Math.round(originalTokenCount / 1000)}k → after: ~${Math.round(compressedTokenCount / 1000)}k\n` +
`• **Saved ~${tokensSaved.toLocaleString('en-US')} tokens (~${percentageSaved}%)**\n` +
`• Timestamp: ${new Date().toLocaleTimeString('en-US')}\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY (from ${toCompress.length} messages)\n${summary}`
};
return [
chatWarningMessage,
visualIndicator,
...messages.slice(-keepLast)
];
} finally {
// Clear the cap timer + host-signal listener on EVERY path (no orphaned timers/listeners).
disposePredictionGuard();
}
} catch (error) {
console.error(`[ContextGuard] Summarization failed: ${(error as Error).message}`);
console.error(`[ContextGuard] Stack: ${(error as Error).stack}`);
}
} else {
debugLog('[COMPRESS]', 'No LM client or summary model configured. Using fallback.');
}
// Fallback if no model, error, or summarization failed
const fallbackSummary = `[ContextGuard Summary: ${toCompress.length} older messages compressed to save context. Original content unavailable due to compression failure or missing model.]`;
debugLog('[COMPRESS]', `Using fallback summary for ${toCompress.length} messages`);
// Track compression info (estimate tokens saved)
const estimatedTokensSaved = Math.round(originalTokenCount * 0.7); // Estimate ~70% savings
this._lastCompressionInfo = {
compressed: true,
originalTokens: originalTokenCount,
compressedTokens: originalTokenCount - estimatedTokensSaved,
messagesCompressed: toCompress.length,
timestamp: new Date()
};
// 🔹 Notify listeners (e.g., AutoTracker) that compression occurred
if (this.onCompression) {
this.onCompression();
}
// Visual indicator for fallback
const fallbackIndicator = {
role: 'system' as const,
content: `🧠 **ContextGuard Compression Active (Fallback Mode)**\n\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
`• Compressed ${toCompress.length} message(s)\n` +
`• Estimated tokens saved: ~${estimatedTokensSaved.toLocaleString('en-US')}\n` +
`• Note: Full summarization unavailable (model not configured or error occurred)\n` +
`• Timestamp: ${new Date().toLocaleTimeString('en-US')}\n` +
`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n` +
`### CONTEXT SUMMARY\n${fallbackSummary}`
};
return [
chatWarningMessage,
fallbackIndicator,
...messages.slice(-keepLast)
];
}
/**
* Arc C (07.10): generate the structured session-continuity summary BEFORE compression destroys history —
* called from promptPreprocessor PART B immediately before compressHistory(), with the caller-side keepLast=10
* exclusion already applied (the last 10 messages survive compression and are deliberately NOT summarized).
*
* Model resolution mirrors compressHistory(): the configured summaryModel first, then the caller-supplied
* fallback id (the active chat model); neither usable → null. Contract: ALWAYS RESOLVES with
* `SessionSummaryData | null` — never throws; any failure (no model/client, wall-clock cap, user stop,
* unparsable output) resolves null so the caller keeps the deterministic telemetry fallback unchanged.
* The prediction reuses the module-private withTimeoutCap() one-controller pattern of compressHistory().
*/
async generateSessionContinuity(
messagesToSummarize: ContextMessage[],
opts?: { fallbackModelId?: string; abortSignal?: AbortSignal },
): Promise<SessionSummaryData | null> {
const modelId = (this.config.summaryModel || '').trim() !== ''
? this.config.summaryModel.trim()
: ((opts?.fallbackModelId ?? '').trim());
if (!modelId || !this.lmClient) {
debugLog('[CONTINUITY]', 'No summary model / fallback id or LM client — skipping continuity generation');
return null;
}
if (messagesToSummarize.length === 0) {
debugLog('[CONTINUITY]', 'Empty message list — nothing to summarize');
return null;
}
// ARC C2a (15.10, owner GO): empty-history gate at the single choke point all three Arc-C trigger sites flow
// through (promptPreprocessor PART B / compressMidLoop step 3 / any future caller). A summarization window with
// NO meaningful user-role content has nothing to summarize — observed 14.10 failure class: a small local model
// asked to summarize an empty history narrated ITS task ("No user request was provided in the conversation
// history.") and that junk row got persisted + indexed. Skip BEFORE the model call (no spend, no persistence).
if (!hasMeaningfulUserContent(messagesToSummarize)) {
// 15.10 owner report: this EXPECTED-OPERATIONAL notice must not land on stderr — Node routes console.warn to
// stderr and the LM Studio host renders plugin stderr lines at ERROR level, so a by-design gate skip read as a
// failure in the log file. Rerouted warn→log (stdout) with byte-identical text; severity marker stays ⚠️ in-text
// (module convention — cf. Tiktoken fallback notices + compressHistory's "instead of stderr logging" precedent).
console.log('[ContextGuard] ⚠️ Arc C continuity SKIPPED: no meaningful user-role content in the summarization window (empty/agent-only history) — skipping summary generation + persistence');
return null;
}
try {
const model = await this.getCachedModel(modelId);
const historyText = messagesToSummarize.map(m => {
const role = (m.role || 'user').toUpperCase();
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `[${role}] ${contentStr}`;
}).join('\n\n');
const continuityPrompt = `You are a session-continuity writer. The conversation history below is about to be compressed and its detail will be lost. Write the exact continuation brief that the next session needs, using ONLY this format (no other text, no code fences):
TASK:
<one or two sentences: what the user asked / the overall task>
ACCOMPLISHMENTS:
- short bullet per item (file paths and names exactly as written); write (none) if nothing was accomplished
PENDING TASKS:
- short bullet per remaining step; write (none) if the work is complete
DECISIONS MADE:
- short bullet with a one-line rationale each; write (none) if no decisions were made
CONTEXT FOR NEXT SESSION:
- exact file paths, anchors and next steps only — pointers, never transcripts
RULES: Preserve ALL file paths, function names, class names, and variable names exactly as written. Be precise but brief (max ~80 words per section). Do not invent work that did not happen in the history below.
CONVERSATION HISTORY TO SUMMARIZE:
${historyText}`;
// Cancellable + capped — same one-controller pattern as compressHistory() (no orphaned timers/listeners).
const { signal: predictionSignal, dispose: disposePredictionGuard } = withTimeoutCap(
opts?.abortSignal,
COMPRESSION_PREDICTION_MAX_MS,
);
try {
const response = model.respond(
[{ role: 'user', content: continuityPrompt }],
{ maxTokens: 1024, temperature: 0.1, signal: predictionSignal },
);
// Wait for the result — host cancel or cap aborts it in-flight (stopReason 'userStopped').
const result = await response.result();
if (result.stats && result.stats.stopReason === 'userStopped') {
throw new Error('Continuity generation stopped by user cancel or prediction cap');
}
const rawContent: string | undefined = typeof result.content === 'string' ? result.content : undefined;
const parsed = parseSessionContinuity(rawContent ?? '');
if (!parsed) {
console.warn('[ContextGuard] ⚠️ Arc C continuity output unparsable (no sections found) — telemetry fallback applies');
return null;
}
// ARC C2b (15.10, owner GO): defense-in-depth at the generate boundary — strip contamination artifacts
// (LSEP tokens / echoed placeholder / reasoning preamble) from every parsed field before returning. The
// persist entry points strip independently too; this keeps whatever is returned here clean for any consumer
// that does not route through persistGeneratedSessionSummary().
for (const key of ['task_description', 'accomplishments', 'pending_tasks', 'decisions_made', 'context_for_next_session'] as const) {
parsed[key] = stripSummaryArtifacts(parsed[key] ?? '');
}
debugLog('[CONTINUITY]', `Generated structured session summary (${rawContent?.length ?? 0} chars raw)`);
return parsed;
} finally {
// Clear the cap timer + host-signal listener on EVERY path (no orphaned timers/listeners).
disposePredictionGuard();
}
} catch (error) {
console.error(`[ContextGuard] Arc C continuity generation failed: ${error instanceof Error ? error.message : String(error)}`);
return null; // non-fatal by contract — telemetry fallback is owned by the caller
}
}
/**
* FIX B (09.10, owner GO) — mid-loop forced compression: runs the SAME pipeline PART B in promptPreprocessor uses at user-message
* boundaries, but callable from inside an agentic tool loop. Before this nothing ran between tier-2's ~90% forced SAVE and the
* model's 100% hard stop — a save persists memory but never shrinks context, so a run-away turn crossing 90% mid-loop accumulated
* straight to the wall (09.10 verification session: turn died at 100%, owner had to enlarge the window; same failure earlier that day).
* The wrapper in toolsProvider.ts calls this ONCE PER TURN when its shared projection crosses PREEMPTIVE_COMPRESSION_PERCENT
* (fixed 95 — always below 100 and above tier-2's compressionPercent crossing); the boundary path stays untouched for turns that
* never cross mid-loop.
*
* Pipeline parity with PART B: (1) store-before-prune of oversized payloads, (2) PART-B telemetry snapshot via
* autoTracker.autoSaveSessionMemory(), (3) Arc-C structured continuity save when enabled, (4) compressHistory() — whose
* onCompression callback → autoTracker.onContextCompressed() fires exactly as at the boundary (FSM re-arms identically).
* Non-fatal contract: steps 1–3 log-and-continue on any failure; step 4 carries compressHistory's own fallback summary. The CALLER
* must swap host history (pop/append) and republish TokenStatsManager baseline/messages — this method only PRODUCES the replacement
* array, it never mutates host state itself.
*/
async compressMidLoop(
messages: ContextMessage[],
opts?: { compactionEnabled?: boolean; forceSummaryOnCompress?: boolean; abortSignal?: AbortSignal; currentTokens?: number; maxTokens?: number },
): Promise<{ compressed: boolean; messages: ContextMessage[] }> {
const keepLast = 10; // same keepLast as PART B / compressHistory — last 10 survive verbatim, deliberately not summarized
if (messages.length <= keepLast) {
console.log(`[ContextGuard] [TIER-2-COMPACT] Mid-loop compression skipped: ${messages.length} message(s) ≤ keepLast(10) — nothing summarizable`);
return { compressed: false, messages };
}
// (1) C compaction family — store-before-prune of oversized payloads, same gate + ordering as PART B. Mid-loop parity matters:
// an unpruned giant payload would sit in keepLast forever and re-fire the threshold almost immediately after compression.
if (opts?.compactionEnabled !== false) {
try {
const refs = collectPrunedPayloadRefs(messages, DEFAULT_MAX_BYTES_PER_RESULT);
if (refs.length > 0) {
for (const ref of refs) {
// Exclusive 'wx' create + 0o600: never overwrites, refuses symlink targets at the path.
await storePrunedPayload(getWorkingDir(), ref);
}
const pruneOutcome = pruneOversizedToolPayloads(messages, { maxBytesPerResult: DEFAULT_MAX_BYTES_PER_RESULT, digests: refs.map((r) => r.digestHex) });
if (pruneOutcome.prunedCount > 0) {
console.log(`[ContextGuard] [TIER-2-COMPACT] Pruned ${pruneOutcome.prunedCount} oversized payload(s) before mid-loop summarization — verbatim copies in .ai_toolbox/compaction/`);
} else {
console.warn(`[ContextGuard] [TIER-2-COMPACT] FAIL-LOUD: ${refs.length} payload(s) collected but NONE pruned — history kept verbatim this pass`);
}
}
} catch (pruneErr) {
// Any store failure aborts pruning for THIS pass only (PART B parity — compress with verbatim payloads).
console.warn(`[ContextGuard] [TIER-2-COMPACT] Prune-before-summarization aborted (non-fatal): ${pruneErr instanceof Error ? pruneErr.message : String(pruneErr)}`);
}
}
// (2) PART-B telemetry snapshot BEFORE history is destroyed — same non-fatal ordering as the boundary path. The caller passes its
// live projection numbers (wrapper `projected`/`limit`); messageCount here = messages.length (best available mid-loop equivalent of
// history.getLength()). Denominator falls back to this guard's own window when absent, so the record never reads NaN/0%.
let snapshotSaved = false;
try {
const tokensUsed = Math.max(0, Math.round(opts?.currentTokens ?? 0));
const denomLimit = (typeof opts?.maxTokens === 'number' && Number.isFinite(opts.maxTokens) && opts.maxTokens > 0) ? opts.maxTokens : this.config.tokenLimit;
const saveResult = await autoTracker.autoSaveSessionMemory(tokensUsed, denomLimit, messages.length);
snapshotSaved = !!saveResult?.saved;
if (snapshotSaved) {
console.log(`[ContextGuard] [TIER-2-COMPACT] ✅ Pre-mid-loop-compression checkpoint saved: ${saveResult.sessionId}`);
} else {
console.warn('[ContextGuard] [TIER-2-COMPACT] ⚠️ Mid-loop compression snapshot NOT saved — compressing without a clean checkpoint');
}
} catch (snapErr) {
console.warn(`[ContextGuard] [TIER-2-COMPACT] Snapshot failed (non-fatal): ${snapErr instanceof Error ? snapErr.message : String(snapErr)}`);
}
// (3) Arc-C structured continuity save — same strict ===true gate + keepLast=10 caller-side exclusion as PART B. The summary model
// resolves inside generateSessionContinuity() (configured summaryModel first; the wrapper passes the active chat id as fallback).
if (opts?.forceSummaryOnCompress === true && messages.length > 10) {
try {
await autoTracker.flushActionsToMemory(); // buffered actions land in the store before the summary spans them (PART B parity)
const toSummarize = messages.slice(0, messages.length - keepLast);
const summary = await this.generateSessionContinuity(toSummarize, { abortSignal: opts?.abortSignal });
if (summary) {
const persistOutcome = await persistGeneratedSessionSummary(summary);
console.log(persistOutcome.saved
? '[ContextGuard] [TIER-2-COMPACT] ✅ Structured continuity summary persisted before mid-loop compression'
: `[ContextGuard] [TIER-2-COMPACT] ⚠️ Continuity summary generated but persistence failed (${persistOutcome.error ?? 'unknown'}) — telemetry only`);
} else {
console.warn('[ContextGuard] [TIER-2-COMPACT] No structured continuity summary available (no usable model) — telemetry fallback applies');
}
} catch (arcErr) {
console.warn(`[ContextGuard] [TIER-2-COMPACT] Forced session-memory save failed (non-fatal): ${arcErr instanceof Error ? arcErr.message : String(arcErr)}`);
}
}
// (4) The compression itself — B1 (29.10, owner GO): compressHistory() decides against the SAME shared-density count that armed
// THIS call (opts.currentTokens = the wrapper's live projection → one counter for gate and decision; the 29.10 divergence where an
// independent SDK/tiktoken recount vetoed a fired pre-emptive gate is impossible on this path by construction), falls back to its own
// summary on prediction failure, and fires onCompression() → autoTracker.onContextCompressed() exactly like the boundary path. When no
// valid count was passed (legacy callers / stubs without opts) compressHistory keeps its pre-B1 independent recount byte-for-byte.
const b1TrustedCount = typeof opts?.currentTokens === 'number' && Number.isFinite(opts.currentTokens) ? opts.currentTokens : undefined;
const compressedMessages = await this.compressHistory(messages, opts?.abortSignal, b1TrustedCount);
// Read-after-await in a single-threaded gap: no interleaving possible — _lastCompressionInfo is set by compressHistory itself on
// EVERY return path (including the below-threshold no-op). Claiming `compressed:true` without this check would lie to the wrapper.
const info = this.getLastCompressionInfo();
if (!info?.compressed) {
console.warn('[ContextGuard] [TIER-2-COMPACT] FAIL-LOUD: pre-emptive gate armed mid-loop compression but compressHistory\'s authoritative count was below its own trigger — NO compression ran, history kept verbatim (safe direction; re-evaluated on the next tool result)');
return { compressed: false, messages };
}
this.resetTokenCache(); // PART B parity — post-compression recount is owned by the caller's republish step
console.log(`[ContextGuard] [TIER-2-COMPACT] ✅ Mid-loop compression complete: ${messages.length} → ${compressedMessages.length} messages (keepLast=${keepLast}, snapshot=${snapshotSaved ? 'saved' : 'missed'})`);
return { compressed: true, messages: compressedMessages };
}
/**
* Helper to count tokens for a specific string using SDK or fallback.
*/
private async _countStringTokens(text: string, modelId?: string): Promise<number> {
if (this.lmClient && modelId) {
try {
const model = await this.getCachedModel(modelId);
if (model && typeof model.countTokens === 'function') {
const rawResult = await model.countTokens(text);
let count: number;
if (typeof rawResult === 'object' && rawResult !== null) {
const obj = rawResult as Record<string, unknown>;
count = ('data' in obj ? Number(obj.data) : 'value' in obj ? Number(obj.value) : 0);
} else if (Array.isArray(rawResult)) {
const arr = rawResult as unknown[];
count = arr.reduce((s: number, v) => s + (typeof v === 'number' ? v : 0), 0);
} else {
count = Number(rawResult) || 0;
}
return count;
}
} catch {}
}
// Fallback to tiktoken — 04.10 ABORT-CONTRACT arc item (c): bounded sync encode, same idiom as the countTokens()
// message loop above. System prompts can be large (serialized tool definitions ride in them) — an unbounded BPE
// here would block the host event loop for seconds. ≤ cap → byte-identical result as before; overflow beyond it
// is estimated with the SAME ratio as the primary heuristic path (shared agentic density via estimateTokensFromChars - see tokenStatsManager), so no under-count that
// could delay compression. Callers today treat this number as a reserved/future-use value, but the WORK still ran.
if (!this.encoder) this.encoder = get_encoding('cl100k_base');
const structuredText = `<|start|>system<|end|>\n${text}`;
const encodable = structuredText.length <= TIKTOKEN_SYNC_ENCODE_CHAR_CAP
? structuredText
: structuredText.slice(0, TIKTOKEN_SYNC_ENCODE_CHAR_CAP);
let tokenCount = this.encoder.encode(encodable).length;
if (structuredText.length > TIKTOKEN_SYNC_ENCODE_CHAR_CAP) {
const overflowChars = structuredText.length - TIKTOKEN_SYNC_ENCODE_CHAR_CAP;
const estimatedOverflowTokens = estimateTokensFromChars(overflowChars);
tokenCount += estimatedOverflowTokens;
console.log(`[ContextGuard] ⚠️ Tiktoken fallback (_countStringTokens): system prompt exceeded ${TIKTOKEN_SYNC_ENCODE_CHAR_CAP.toLocaleString('en-US')} chars — encoded cap precisely, +${estimatedOverflowTokens.toLocaleString('en-US')} tokens estimated for the overflow (shared agentic density - see tokenStatsManager) to keep the sync encode bounded.`);
}
return tokenCount + 8; // +8 for overhead/BOS
}
// 📊 Percent-based trigger (07.10) — mirrors compressHistory() so external consumers (preprocessor,
// AutoTracker gates) always agree with the internal compression decision.
getThreshold(): number {
return this.config.tokenLimit * (this.config.compressionPercent / 100);
}
/**
* Resets the token cache when history changes.
*/
resetTokenCache() {
this.cachedTokenCount = null;
}
/**
* Gets the current token budget information as a human-readable string.
*/
getTokenBudgetInfo(): string {
const current = this.cachedTokenCount ?? 0;
const limit = this.config.tokenLimit;
const percentage = Math.round((current / limit) * 100);
return `[ContextGuard] Budget: ${Math.round(current / 1000)}k/${Math.round(limit / 1000)}k tokens (${percentage}% used)`;
}
/**
* Gets the configured token limit.
*/
getTokenLimit(): number {
return this.config.tokenLimit;
}
/**
* Receives prediction stats from LM Studio's inference engine.
* This replaces estimation with actual token counts from PredictionResult.stats,
* matching exactly what LM Studio's sidebar displays.
*
* Call this after awaiting on model.respond() or model.complete().result()
* to update the cached token count with authoritative SDK data.
*
* DORMANT WIRING (FIX #20, 23.08): no caller in src/ — this path is only fed by a registered
* prediction-loop handler / model.respond() consumer. LM Studio Core REJECTS plugins that register
* BOTH a tools provider and a predictionLoopHandler ("Tools provider cannot be used with a
* predictionLoopHandler" — boot crash verified 21.08; SDK v1.5.0 was latest as of 22.08, no upgrade
* path). ai_toolbox is a tools plugin, so this hook stays inactive by design until core changes.
* The mid-loop gap it would have closed is now covered by TokenStatsManager A1 delta bookkeeping +
* AutoTracker.guardMidLoopThreshold (see future_improvements/autoTracker_midloop_fix_plan.md).
*
* @param stats - LLMPredictionStats from PredictionResult.stats
*/
receivePredictionStats(stats: LLMPredictionStats): void {
// Update the TokenStatsManager so other components can access it
TokenStatsManager.updateFromPredictionResult(stats);
// Also update our cached count if totalTokensCount is available
if (stats.totalTokensCount != null && stats.totalTokensCount > 0) {
this.cachedTokenCount = stats.totalTokensCount;
console.log(`[ContextGuard] ✅ Updated token count from LM Studio SDK: ${stats.totalTokensCount.toLocaleString('en-US')} tokens`);
// Log the full summary for debugging
const summary = TokenStatsManager.getSummary();
if (summary) {
debugLog('[ContextGuard]', summary);
}
} else {
console.warn(`[ContextGuard] ⚠️ Prediction stats received but totalTokensCount is invalid:`, stats);
}
}
/**
* Get the latest prediction summary from LM Studio's inference engine.
* Returns null if no predictions have been made yet.
*/
getPredictionStatsSummary(): string | null {
return TokenStatsManager.getSummary();
}
/**
* Updates the configuration dynamically.
*/
updateConfig(newConfig: Partial<ContextGuardConfig>): void {
this.config = { ...this.config, ...newConfig };
}
/**
* Sets or updates the LM Studio client reference for dynamic model queries.
*/
setLMClient(client: LMStudioClient | null): void {
this.lmClient = client;
}
/**
* Dynamically fetches and applies the actual context window length from the active LM Studio model.
*/
async setTokenLimitFromModel(modelId?: string): Promise<void> {
if (!this.lmClient) return; // Cannot query without client
try {
let model;
if (modelId && typeof modelId === 'string' && modelId.trim() !== '') {
// User provided explicit model ID — load it directly
console.log(`[ContextGuard] Loading specified model: ${modelId}`);
model = await this.getCachedModel(modelId);
} else {
// No model ID provided — use SDK's official pattern: call .model() without arguments
// This returns the currently loaded/active model (see LM Studio plugin examples)
debugLog('[ContextGuard] No explicit model ID. Using SDK auto-detection...');
try {
// Call .model() without arguments to get the currently active model
model = await this.lmClient.llm.model();
if (model) {
console.log(`[ContextGuard] ✅ Auto-detected active model via SDK`);
} else {
debugLog('[ContextGuard] No active model detected. Using default tokenLimit.');
}
} catch (err) {
debugLog(`[ContextGuard] Failed to detect active model: ${(err as Error).message}. Using default tokenLimit.`);
}
}
if (!model) {
// If auto-detection fails, keep the current effective window (last model-reported value or the built-in 30k startup fallback — see index.ts)
const configLimit = this.config.tokenLimit;
console.log(`[ContextGuard] ⚠️ Auto-detection failed. Using configured tokenLimit: ${configLimit}.`);
return; // Keep existing config.tokenLimit (which should come from plugin settings)
}
// ✅ Use SDK's native getContextLength() API (LM Studio TS v1.x+)
const typedModel = model as LLMModelWithOptionalMethods;
if (typeof typedModel.getContextLength === 'function') {
const actualContextLength = await typedModel.getContextLength();
if (actualContextLength > 0) {
this.config.tokenLimit = actualContextLength;
console.log(`[ContextGuard] ✅ Updated tokenLimit from SDK: ${actualContextLength}`);
} else {
const configLimit = this.config.tokenLimit;
console.warn(`[ContextGuard] getContextLength() returned ${actualContextLength}. Using configured limit: ${configLimit}`);
}
} else if (typedModel.config?.contextSize != null) {
// Fallback: read from model config if available
const fallbackLimit = typedModel.config.contextSize as number;
this.config.tokenLimit = fallbackLimit;
console.log(`[ContextGuard] ✅ Fetched contextSize from model config: ${fallbackLimit}`);
}
} catch (err) {
const configLimit = this.config.tokenLimit;
console.error(`[ContextGuard] Failed to fetch actual context length. Using configured limit: ${configLimit} (${(err as Error).message})`);
}
}
/**
* Gets the current cached token count (for external monitoring).
*/
getCurrentTokenCount(): number {
return this.cachedTokenCount ?? 0;
}
/**
* Smartly reads a file using Keyword-Grep for precision.
* FIX #3: Added max_length parameter to respect caller's truncation limits.
*/
smartRead(filePath: string, userPrompt?: string, maxLength?: number): string {
if (!this.config.smartReading) {
const content = readFileSync(filePath, 'utf-8');
return maxLength ? content.substring(0, maxLength) : content;
}
try {
const stats = statSync(filePath);
this.trackedFiles.set(filePath, { compressed: false, truncated: true, originalSize: stats.size });
const content = readFileSync(filePath, 'utf-8');
const lines = content.split('\n');
// FIX #3: Use caller's maxLength if provided, otherwise use defaults
const effectiveMaxLength = maxLength || 5000;
const maxLines = 2000;
const maxBytes = 100 * 1024;
// Return full content only if file is small AND within caller's limit
if (stats.size < maxBytes && lines.length < maxLines && content.length <= effectiveMaxLength) {
return content;
}
const keywords = this.extractKeywords(userPrompt || '');
let relevantLines: number[] = [];
if (keywords.length > 0) {
lines.forEach((line, index) => {
if (keywords.some(kw => line.toLowerCase().includes(kw.toLowerCase()))) {
relevantLines.push(index);
}
});
if (relevantLines.length > 0) {
const result = this.formatRelevantLines(lines, relevantLines);
// FIX #3: Truncate to maxLength even for smart-read results
return result.length > effectiveMaxLength
? result.substring(0, effectiveMaxLength) + `\n// [ContextGuard] Output truncated to ${effectiveMaxLength} chars`
: result;
}
}
// Fallback: header/footer view
const header = lines.slice(0, 50).join('\n');
const footer = lines.slice(-50).join('\n');
let fallbackResult = `// [ContextGuard] File truncated due to size (${stats.size} bytes)\n// --- HEADER (First 50 lines) ---\n${header}\n// --- FOOTER (Last 50 lines) ---\n${footer}\n// [ContextGuard] Content truncated for context efficiency.`;
// FIX #3: Respect maxLength on fallback too
if (fallbackResult.length > effectiveMaxLength) {
fallbackResult = fallbackResult.substring(0, effectiveMaxLength) + `\n// [ContextGuard] Output truncated to ${effectiveMaxLength} chars`;
}
return fallbackResult;
} catch (error) {
return `Error reading file: ${(error as Error).message}`;
}
}
/**
* Filters terminal output to prevent context bloat.
*/
filterTerminalOutput(output: string): string {
if (!this.config.terminalFilterEnabled) return output;
const threshold = this.config.terminalFilterLength || 2000;
if (output.length <= threshold) return output;
const lines = output.split('\n');
const head = lines.slice(0, 5).join('\n');
const tail = lines.slice(-5).join('\n');
return `${head}\n... [Output truncated: ${lines.length - 10} lines hidden] ...\n${tail}`;
}
/**
* Forces a fresh read of a tracked file (Re-RAG Trigger).
*/
reloadContextForFile(filePath: string): string {
if (this.trackedFiles.has(filePath)) {
this.trackedFiles.delete(filePath);
return `// [ContextGuard] Context reloaded for ${filePath}. Previous compression/truncation cleared.`;
}
return `// [ContextGuard] No tracked context for ${filePath}. Reading normally.`;
}
/**
* Compresses a specific file's tracked context (marks it as compressed).
*/
markFileAsCompressed(filePath: string): void {
if (this.trackedFiles.has(filePath)) {
const info = this.trackedFiles.get(filePath);
if (info) {
this.trackedFiles.set(filePath, { ...info, compressed: true });
}
} else {
// If not tracked yet, add it as compressed
try {
const stats = statSync(filePath);
this.trackedFiles.set(filePath, { compressed: true, truncated: false, originalSize: stats.size });
} catch {
console.error(`[ContextGuard] Cannot mark file as compressed - file not found: ${filePath}`);
}
}
}
/**
* Computes a simple hash of messages for cache invalidation.
* FIX #1: Ensures cache is invalidated when every message changes, not just the last one.
*/
private computeMessageHash(messages: ContextMessage[]): string {
return messages.map(m => {
const contentStr: string = typeof m.content === 'string'
? m.content
: m.content != null && typeof m.content !== 'string'
? JSON.stringify(m.content)
: '';
return `${m.role}:${contentStr}`;
}).join('||');
}
/**
* Extracts meaningful keywords from a prompt for smart file reading.
*/
private extractKeywords(prompt: string): string[] {
const matches = prompt.match(/\b[a-zA-Z_$][a-zA-Z0-9_$]*\b/g);
if (!matches) return [];
// Filter out stop words and keep only meaningful identifiers (length > 4)
return [...new Set(matches)]
.filter(w => w.length > 4 && !STOP_WORDS.has(w.toLowerCase()));
}
/**
* Formats relevant lines with context margins for smart reading.
*/
private formatRelevantLines(lines: string[], indices: number[]): string {
let result = '';
const margin = 5;
indices.forEach(index => {
const start = Math.max(0, index - margin);
const end = Math.min(lines.length, index + margin + 1);
result += `// ... [Match at line ${index + 1}] ... \n`;
result += lines.slice(start, end).join('\n') + '\n';
});
return result;
}
}
/**
* Hub-Exclusion Clustering Integration for ContextGuard
*
* Provides architectural transparency insights during context analysis:
* - Identifies which modules are hubs vs regular members
* - Tracks cluster membership for tracked files
* - Enables cluster-aware compression strategies
*/
import type { HubExclusionResult } from './utils/hubExclusionClustering.js';
import { analyzeAiToolboxDependencies } from './utils/hubExclusionClustering.js';
/**
* Cache for clustering analysis results (avoid recomputation).
*/
let cachedClusteringResult: HubExclusionResult | null = null;
let clusteringCacheTimestamp = 0;
/**
* Get or compute the Hub-Exclusion Clustering result.
* Cached for performance — invalidates after 5 minutes.
*/
function getClusteringResult(): HubExclusionResult {
const now = Date.now();
if (cachedClusteringResult && (now - clusteringCacheTimestamp) < 5 * 60 * 1000) {
return cachedClusteringResult;
}
cachedClusteringResult = analyzeAiToolboxDependencies();
clusteringCacheTimestamp = now;
debugLog('[CLUSTERING]', `Computed Hub-Exclusion Clustering: ${cachedClusteringResult.nodes.length} modules, ${cachedClusteringResult.clusters.length} clusters`);
return cachedClusteringResult;
}
/**
* Get the cluster membership for a given file/module path.
*/
export function getFileClusterInfo(filePath: string): {
isHub: boolean;
clusterId?: number;
moduleDegree: number;
clusterSize?: number;
clusterDensity?: number;
} | null {
const result = getClusteringResult();
// Normalize the file path to match node IDs in the clustering result
const normalizedPath = filePath.replace(/\\/g, '/').replace(/^.*\/src\//, '');
const matchingNode = result.nodes.find(n => n.id.includes(normalizedPath) || normalizedPath.includes(n.id));
if (!matchingNode) return null;
const isHub = result.hubs.includes(matchingNode.id);
let clusterId: number | undefined;
let clusterSize: number | undefined;
let clusterDensity: number | undefined;
// Find the cluster this node belongs to (or a hub's assigned cluster)
for (const cluster of result.clusters) {
if (cluster.members.includes(matchingNode.id)) {
clusterId = cluster.clusterId;
clusterSize = cluster.size;
clusterDensity = cluster.density;
break;
}
}
// If it's a hub, check its assignment
if (!clusterId && result.hubAssignments[matchingNode.id] != null) {
const assignedClusterId = result.hubAssignments[matchingNode.id];
if (assignedClusterId >= 0) {
clusterId = assignedClusterId;
const assignedCluster = result.clusters.find(c => c.clusterId === assignedClusterId);
clusterSize = assignedCluster?.size;
clusterDensity = assignedCluster?.density;
}
}
return {
isHub,
clusterId,
moduleDegree: matchingNode.degree,
clusterSize,
clusterDensity
};
}
/**
* Generate an architectural insight summary for the current context.
*
* Used during compression to provide users with insights about which
* modules are being affected and their roles in the architecture.
*/
export function getArchitecturalInsights(): string {
const result = getClusteringResult();
let insights = '\n🏗️ Architectural Context Summary\n';
insights += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
// Module distribution
insights += `Modules analyzed: ${result.nodes.length}\n`;
insights += `Clusters identified: ${result.clusters.length}\n`;
insights += `Hub modules: ${result.hubs.length}\n\n`;
// Hub roles
if (result.hubs.length > 0) {
insights += '🔶 Architectural Hubs:\n';
for (const hubId of result.hubs.slice(0, 5)) {
const node = result.nodes.find(n => n.id === hubId);
if (node) {
insights += ` • ${node.label || hubId} — connects ${node.degree} modules\n`;
}
}
if (result.hubs.length > 5) {
insights += ` ... and ${result.hubs.length - 5} more hubs\n`;
}
insights += '\n';
}
// Cluster summary
insights += '📦 Module Clusters:\n';
for (const cluster of result.clusters.slice(0, 3)) {
const densityStr = cluster.density != null ? ` | density: ${cluster.density.toFixed(2)}` : '';
insights += ` Cluster ${cluster.clusterId}: ${cluster.size} modules${densityStr}\n`;
// Show representative members
for (const member of cluster.members.slice(0, 3)) {
const node = result.nodes.find(n => n.id === member);
if (node) {
insights += ` • ${node.label || member}\n`;
}
}
}
// Modularity quality
if (result.modularity != null) {
const quality = result.modularity > 0.3 ? 'Strong' : result.modularity > 0.2 ? 'Moderate' : 'Weak';
insights += `\n📊 Clustering quality: ${quality} (${result.modularity.toFixed(3)})\n`;
}
return insights;
}
/**
* Check if a file belongs to a hub module — useful for compression priority.
* Hub modules should be preserved during context compression as they are
* architecturally critical.
*/
export function isHubModule(filePath: string): boolean {
const info = getFileClusterInfo(filePath);
return info?.isHub ?? false;
}
/**
* Get the cluster ID for a file — useful for cluster-aware compression strategies.
* Files in the same cluster can be compressed together to reduce redundancy.
*/
export function getModuleClusterId(filePath: string): number | null {
const info = getFileClusterInfo(filePath);
return info?.clusterId ?? null;
}
/**
* Compress files from the same cluster together (optimization).
*
* When multiple tracked files belong to the same cluster, they can be
* compressed in a single operation rather than individually.
*/
export function groupTrackedFilesByCluster(trackedPaths: string[]): Map<number, string[]> {
const clusters = new Map<number, string[]>();
for (const filePath of trackedPaths) {
const clusterId = getModuleClusterId(filePath);
if (clusterId != null && clusterId >= 0) {
if (!clusters.has(clusterId)) {
clusters.set(clusterId, []);
}
clusters.get(clusterId)!.push(filePath);
} else {
// Files not in any cluster or hubs go to a special group
const unclustered = clusters.get(-1);
if (!unclustered) {
clusters.set(-1, [filePath]);
} else {
unclustered.push(filePath);
}
}
}
return clusters;
}