@grapine.ai/contextprune 0.1.0 → 0.1.2

package/dist/src/pipeline/index.js

@@ -0,0 +1,167 @@
+"use strict";
+// src/pipeline/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPipeline = runPipeline;
+const classifier_1 = require("../classifier");
+const scorer_1 = require("../scorer");
+const session_extractor_1 = require("../scorer/session-extractor");
+const selector_1 = require("../strategy/selector");
+const engine_1 = require("../compression/engine");
+const coherence_1 = require("../validation/coherence");
+const utils_1 = require("../utils");
+const brief_1 = require("../brief");
+async function runPipeline(messages, model, options = {}) {
+    const sessionId = (0, utils_1.generateId)();
+    // Stage 1: Classify
+    const annotated = await (0, classifier_1.classifyAll)(messages, model);
+    // Stage 2: Extract session state + score
+    const sessionState = (0, session_extractor_1.extractSessionState)(annotated, model, options.actualInputTokens);
+    const scored = (0, scorer_1.scoreAll)(annotated, sessionState);
+    // Stage 3: Select strategies
+    // manual mode = always compress; use 0.70 so the strategy table fires for stale
+    // content but does NOT escalate fresh active tool outputs (escalation needs >= 0.80)
+    const effectiveUtilization = options.compressionMode === 'manual'
+        ? Math.max(sessionState.tokenBudget.utilizationPercent, 0.70)
+        : sessionState.tokenBudget.utilizationPercent;
+    const withStrategies = (0, selector_1.selectAllStrategies)(scored, effectiveUtilization);
+    // Stage 4: Compress — skip if suggest-only or auto mode hasn't hit threshold
+    const suggestOnly = options.compressionMode === 'suggest-only';
+    const utilization = sessionState.tokenBudget.utilizationPercent;
+    const warningThreshold = options.warningThreshold ?? 0.65;
+    const autoSkip = options.compressionMode === 'auto' && utilization < warningThreshold;
+    const compressionResult = (suggestOnly || autoSkip)
+        ? null
+        : await (0, engine_1.compress)(withStrategies, model, options.useLLMSummarization ?? false);
+    // Stage 5: Validate (only when compression ran)
+    let finalMessages = messages;
+    if (compressionResult) {
+        const validation = (0, coherence_1.validate)(annotated, compressionResult.compressed, compressionResult.event.decisions, sessionState);
+        finalMessages = validation.passed
+            ? compressionResult.compressed
+            : (0, coherence_1.restoreMessages)(annotated, compressionResult.compressed, validation.blockers);
+    }
+    const tokensBefore = compressionResult?.event.tokensBefore
+        ?? annotated.reduce((s, m) => s + m.tokenCount, 0);
+    // When compression didn't run, estimate savings from selected strategies
+    const projectedSaved = withStrategies.reduce((sum, msg) => {
+        switch (msg.compressionStrategy) {
+            case 'DROP':
+            case 'DEDUPLICATE': return sum + msg.tokenCount;
+            case 'COLLAPSE_TO_MARKER': return sum + Math.max(0, msg.tokenCount - 15);
+            case 'EXTRACT_RESULT': return sum + Math.floor(msg.tokenCount * 0.5);
+            case 'SUMMARIZE': return sum + Math.floor(msg.tokenCount * 0.65);
+            default: return sum;
+        }
+    }, 0);
+    const tokensSaved = compressionResult?.event.tokensSaved ?? projectedSaved;
+    const tokensAfter = compressionResult?.event.tokensAfter ?? (tokensBefore - tokensSaved);
+    // Assemble outputs
+    const compressed = {
+        messages: finalMessages,
+        summary: {
+            tokensBefore,
+            tokensAfter,
+            tokensSaved,
+            savingsPercent: tokensBefore > 0 ? tokensSaved / tokensBefore : 0,
+            messagesRemoved: messages.length - finalMessages.length,
+            compressionTriggered: compressionResult !== null,
+        },
+        sessionId,
+    };
+    const decisions = compressionResult?.event.decisions ?? [];
+    const sessionBrief = (0, brief_1.generateSessionBrief)(annotated);
+    const analysis = {
+        sessionId,
+        annotatedMessages: annotated,
+        breakdown: buildBreakdown(annotated),
+        topConsumers: buildTopConsumers(annotated),
+        recommendation: buildRecommendation(sessionState, { tokensBefore, tokensSaved }),
+        sessionState,
+        sessionBrief,
+        compressionHistory: [{
+                eventId: (0, utils_1.generateId)(),
+                timestamp: new Date(),
+                trigger: 'api_call',
+                messagesEvaluated: annotated.length,
+                messagesCompressed: decisions.filter(d => d.strategy !== 'PRESERVE').length,
+                messagesDropped: decisions.filter(d => d.strategy === 'DROP' || d.strategy === 'DEDUPLICATE').length,
+                messagesPreserved: decisions.filter(d => d.strategy === 'PRESERVE').length,
+                tokensBefore,
+                tokensAfter,
+                tokensSaved,
+                savingsPercent: tokensBefore > 0 ? tokensSaved / tokensBefore : 0,
+                decisions,
+            }],
+    };
+    return { compressed, analysis };
+}
+// ─── Output Builders ──────────────────────────────────────────────────────────
+function buildBreakdown(annotated) {
+    const byClassification = {};
+    const byCompressionStrategy = {};
+    const totalTokens = annotated.reduce((s, m) => s + m.tokenCount, 0);
+    for (const msg of annotated) {
+        if (!byClassification[msg.classification]) {
+            byClassification[msg.classification] = { count: 0, tokens: 0, percentOfTotal: 0 };
+        }
+        byClassification[msg.classification].count++;
+        byClassification[msg.classification].tokens += msg.tokenCount;
+        byClassification[msg.classification].percentOfTotal =
+            byClassification[msg.classification].tokens / (totalTokens || 1);
+        if (!byCompressionStrategy[msg.compressionStrategy]) {
+            byCompressionStrategy[msg.compressionStrategy] = { count: 0, tokensBefore: 0, tokensAfter: 0 };
+        }
+        byCompressionStrategy[msg.compressionStrategy].count++;
+        byCompressionStrategy[msg.compressionStrategy].tokensBefore += msg.tokenCount;
+        byCompressionStrategy[msg.compressionStrategy].tokensAfter += msg.compressedTokenCount ?? msg.tokenCount;
+    }
+    return { byClassification, byCompressionStrategy };
+}
+function buildTopConsumers(annotated) {
+    const totalTokens = annotated.reduce((s, m) => s + m.tokenCount, 0);
+    return [...annotated]
+        .sort((a, b) => b.tokenCount - a.tokenCount)
+        .slice(0, 10)
+        .map((msg) => ({
+        messageId: msg.id,
+        originalIndex: msg.originalIndex,
+        classification: msg.classification,
+        tokenCount: msg.tokenCount,
+        percentOfTotal: msg.tokenCount / (totalTokens || 1),
+        compressionOpportunity: getOpportunity(msg.compressionStrategy),
+        reason: getOpportunityReason(msg.classification),
+    }));
+}
+function getOpportunity(strategy) {
+    if (strategy === 'PRESERVE')
+        return 'none';
+    if (strategy === 'DROP' || strategy === 'EXTRACT_RESULT')
+        return 'high';
+    if (strategy === 'COLLAPSE_TO_MARKER' || strategy === 'SUMMARIZE')
+        return 'medium';
+    return 'low';
+}
+function getOpportunityReason(classification) {
+    const reasons = {
+        TOOL_OUTPUT_STALE: 'Stale tool output — no longer referenced',
+        ERROR_RESOLVED: 'Resolved error — stack trace no longer needed',
+        REASONING_INTERMEDIATE: 'Intermediate reasoning — conclusion already reached',
+        PROGRESS_MARKER: 'Completed step — collapsible to single line',
+        CONVERSATIONAL: 'General exchange — low active relevance',
+    };
+    return reasons[classification] ?? 'Low relevance score';
+}
+function buildRecommendation(sessionState, result) {
+    const util = sessionState.tokenBudget.utilizationPercent;
+    const savings = result.tokensBefore > 0 ? result.tokensSaved / result.tokensBefore : 0;
+    if (util < 0.50) {
+        return { shouldCompress: false, urgency: 'none', projectedSavings: result.tokensSaved, projectedSavingsPercent: savings, message: `Context is ${Math.round(util * 100)}% full. No compression needed yet.` };
+    }
+    if (util < 0.65) {
+        return { shouldCompress: false, urgency: 'suggested', projectedSavings: result.tokensSaved, projectedSavingsPercent: savings, message: `Context is ${Math.round(util * 100)}% full. Compression available but not urgent.` };
+    }
+    if (util < 0.80) {
+        return { shouldCompress: true, urgency: 'recommended', projectedSavings: result.tokensSaved, projectedSavingsPercent: savings, message: `Context is ${Math.round(util * 100)}% full. Recommend compressing — ${Math.round(savings * 100)}% savings available.` };
+    }
+    return { shouldCompress: true, urgency: 'critical', projectedSavings: result.tokensSaved, projectedSavingsPercent: savings, message: `Context is ${Math.round(util * 100)}% full. Compress now — model quality is degrading. ${Math.round(savings * 100)}% savings available.` };
+}

package/dist/src/scorer/index.d.ts

@@ -0,0 +1,4 @@
+import type { AnnotatedMessage, SessionState, RelevanceTier } from '../types';
+export declare function scoreTierFromScore(score: number): RelevanceTier;
+export declare function scoreRelevance(message: AnnotatedMessage, allMessages: AnnotatedMessage[], sessionState: SessionState): number;
+export declare function scoreAll(messages: AnnotatedMessage[], sessionState: SessionState): AnnotatedMessage[];

package/dist/src/scorer/index.js

@@ -0,0 +1,136 @@
+"use strict";
+// src/scorer/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreTierFromScore = scoreTierFromScore;
+exports.scoreRelevance = scoreRelevance;
+exports.scoreAll = scoreAll;
+const utils_1 = require("../utils");
+const classifier_1 = require("../classifier");
+// ─── Type Weight Table ────────────────────────────────────────────────────────
+const TYPE_WEIGHTS = {
+    SYSTEM_CONSTRAINT: 1.0,
+    USER_CORRECTION: 1.0,
+    TASK_DEFINITION: 1.0,
+    ERROR_ACTIVE: 1.0,
+    TOOL_OUTPUT_ACTIVE: 0.80,
+    DECISION_FINAL: 0.75,
+    PROGRESS_MARKER: 0.50,
+    CONVERSATIONAL: 0.45,
+    TOOL_OUTPUT_STALE: 0.20,
+    ERROR_RESOLVED: 0.15,
+    REASONING_INTERMEDIATE: 0.20,
+};
+const WEIGHTS = {
+    recency: 0.25,
+    references: 0.30,
+    taskProximity: 0.20,
+    typeWeight: 0.25,
+};
+// ─── Factor: Recency ──────────────────────────────────────────────────────────
+function recencyScore(messageIndex, totalMessages, classification) {
+    if ((0, classifier_1.isPinned)(classification))
+        return 1.0;
+    const turnsFromEnd = totalMessages - 1 - messageIndex;
+    // Asymptotic decay: 1 / (1 + k * turnsFromEnd)
+    const k = 0.15;
+    return 1 / (1 + k * turnsFromEnd);
+}
+// ─── Factor: References ───────────────────────────────────────────────────────
+function directlyReferences(source, later) {
+    // Method 1: Tool use ID (exact)
+    const sourceContent = Array.isArray(source.original.content)
+        ? source.original.content
+        : [];
+    const sourceToolId = sourceContent.find((b) => b.id || b.tool_use_id);
+    if (sourceToolId) {
+        const id = sourceToolId.id ?? sourceToolId.tool_use_id;
+        if (id && JSON.stringify(later.original.content).includes(id))
+            return true;
+    }
+    // Method 2: Keyword overlap for short messages
+    if (source.tokenCount < 200) {
+        const sourceKws = (0, utils_1.extractKeywords)((0, utils_1.extractText)(source.original));
+        const laterKws = (0, utils_1.extractKeywords)((0, utils_1.extractText)(later.original));
+        const overlap = sourceKws.filter((k) => laterKws.includes(k));
+        const ratio = overlap.length / Math.max(sourceKws.length, 1);
+        if (ratio > 0.35)
+            return true;
+    }
+    return false;
+}
+function countDirectReferences(message, allMessages) {
+    const later = allMessages.slice(message.originalIndex + 1);
+    return later.filter((m) => directlyReferences(message, m)).length;
+}
+function referenceScore(message, allMessages) {
+    const later = allMessages.slice(message.originalIndex + 1);
+    if (later.length === 0)
+        return 1.0; // most recent message — assumed highly relevant
+    // Fast path: skip expensive check for very old messages
+    const turnsFromEnd = allMessages.length - message.originalIndex;
+    if (turnsFromEnd > 40)
+        return 0.0;
+    const refCount = countDirectReferences(message, allMessages);
+    if (refCount === 0)
+        return 0.0;
+    return Math.min(1.0, 0.5 + (Math.log(refCount + 1) / Math.log(4)) * 0.5);
+}
+// ─── Factor: Task Proximity ───────────────────────────────────────────────────
+function taskProximityScore(message, sessionState) {
+    const messageText = (0, utils_1.extractText)(message.original).toLowerCase();
+    let score = 0.3;
+    if (sessionState.taskContext.currentSubtask) {
+        const subtaskKws = (0, utils_1.extractKeywords)(sessionState.taskContext.currentSubtask);
+        const messageKws = (0, utils_1.extractKeywords)(messageText);
+        const overlap = subtaskKws.filter((k) => messageKws.includes(k));
+        score += Math.min(0.4, overlap.length * 0.15);
+    }
+    const techStack = sessionState.taskContext.technologyStack;
+    if (techStack.some((t) => messageText.includes(t.toLowerCase()))) {
+        score += 0.15;
+    }
+    const mentionsCompleted = sessionState.taskContext.completedSubtasks.some((task) => (0, utils_1.extractKeywords)(task).some((k) => messageText.includes(k)));
+    if (mentionsCompleted)
+        score -= 0.10;
+    return Math.max(0, Math.min(1.0, score));
+}
+// ─── Tier Conversion ──────────────────────────────────────────────────────────
+function scoreTierFromScore(score) {
+    if (score >= 0.85)
+        return 'CRITICAL';
+    if (score >= 0.65)
+        return 'HIGH';
+    if (score >= 0.40)
+        return 'MEDIUM';
+    if (score >= 0.20)
+        return 'LOW';
+    return 'NEGLIGIBLE';
+}
+// ─── Composite Scorer ─────────────────────────────────────────────────────────
+function scoreRelevance(message, allMessages, sessionState) {
+    if (message.relevanceFactors.isPinned)
+        return 1.0;
+    const recency = recencyScore(message.originalIndex, allMessages.length, message.classification);
+    const references = referenceScore(message, allMessages);
+    const proximity = taskProximityScore(message, sessionState);
+    const typeWeight = TYPE_WEIGHTS[message.classification];
+    return (recency * WEIGHTS.recency +
+        references * WEIGHTS.references +
+        proximity * WEIGHTS.taskProximity +
+        typeWeight * WEIGHTS.typeWeight);
+}
+// ─── Batch Scorer ─────────────────────────────────────────────────────────────
+function scoreAll(messages, sessionState) {
+    for (const message of messages) {
+        const score = scoreRelevance(message, messages, sessionState);
+        const refCount = countDirectReferences(message, messages);
+        message.relevanceScore = score;
+        message.relevanceFactors = {
+            ...message.relevanceFactors,
+            recencyScore: recencyScore(message.originalIndex, messages.length, message.classification),
+            referenceCount: refCount,
+            taskProximity: taskProximityScore(message, sessionState),
+        };
+    }
+    return messages;
+}

package/dist/src/scorer/session-extractor.d.ts

@@ -0,0 +1,2 @@
+import type { AnnotatedMessage, SessionState } from '../types';
+export declare function extractSessionState(messages: AnnotatedMessage[], model: string, actualInputTokens?: number): SessionState;

package/dist/src/scorer/session-extractor.js

@@ -0,0 +1,57 @@
+"use strict";
+// src/scorer/session-extractor.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSessionState = extractSessionState;
+const utils_1 = require("../utils");
+const tokenizer_1 = require("../tokenizer");
+const utils_2 = require("../utils");
+const patterns_1 = require("../classifier/patterns");
+function extractSessionState(messages, model, actualInputTokens) {
+    const taskDef = messages.find((m) => m.classification === 'TASK_DEFINITION');
+    const allProgress = messages.filter((m) => m.classification === 'PROGRESS_MARKER');
+    const lastProgress = allProgress[allProgress.length - 1];
+    const lastUserMessage = [...messages].reverse().find((m) => m.original.role === 'user');
+    const completedSubtasks = allProgress
+        .slice(0, -1)
+        .map((m) => (0, utils_1.extractText)(m.original));
+    const activeConstraints = messages
+        .filter((m) => m.classification === 'USER_CORRECTION' ||
+        m.classification === 'SYSTEM_CONSTRAINT')
+        .map((m) => (0, utils_1.extractText)(m.original));
+    const allText = messages.map((m) => (0, utils_1.extractText)(m.original)).join(' ').toLowerCase();
+    const technologyStack = detectTechStack(allText);
+    const computedUsage = messages.reduce((sum, m) => sum + m.tokenCount, 0);
+    const currentUsage = actualInputTokens ?? computedUsage;
+    const modelMaxTokens = (0, tokenizer_1.getModelMaxTokens)(model);
+    return {
+        sessionId: (0, utils_2.generateId)(),
+        createdAt: new Date(),
+        lastUpdatedAt: new Date(),
+        taskContext: {
+            originalGoal: taskDef ? (0, utils_1.extractText)(taskDef.original) : null,
+            currentSubtask: lastProgress
+                ? (0, utils_1.extractText)(lastProgress.original)
+                : lastUserMessage
+                    ? (0, utils_1.extractText)(lastUserMessage.original)
+                    : null,
+            completedSubtasks,
+            activeConstraints,
+            technologyStack,
+        },
+        tokenBudget: {
+            modelMaxTokens,
+            currentUsage,
+            utilizationPercent: currentUsage / modelMaxTokens,
+            warningThreshold: 0.65,
+            criticalThreshold: 0.80,
+        },
+        messages: new Map(messages.map((m) => [m.id, m])),
+        messageOrder: messages.map((m) => m.id),
+        compressionHistory: [],
+    };
+}
+function detectTechStack(text) {
+    return Object.entries(patterns_1.TECH_STACK_SIGNALS)
+        .filter(([, pattern]) => pattern.test(text))
+        .map(([name]) => name);
+}

package/dist/src/strategy/selector.d.ts

@@ -0,0 +1,3 @@
+import type { AnnotatedMessage, CompressionStrategy } from '../types';
+export declare function selectStrategy(message: AnnotatedMessage, utilizationPercent: number): CompressionStrategy;
+export declare function selectAllStrategies(messages: AnnotatedMessage[], utilizationPercent: number): AnnotatedMessage[];

package/dist/src/strategy/selector.js

@@ -0,0 +1,158 @@
+"use strict";
+// src/strategy/selector.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStrategy = selectStrategy;
+exports.selectAllStrategies = selectAllStrategies;
+const confidence_1 = require("../classifier/confidence");
+const scorer_1 = require("../scorer");
+const classifier_1 = require("../classifier");
+// ─── Decision Table ───────────────────────────────────────────────────────────
+function key(c, r, conf) {
+    return `${c}::${r}::${conf}`;
+}
+const STRATEGY_TABLE = {
+    // SYSTEM_CONSTRAINT — always preserve
+    [key('SYSTEM_CONSTRAINT', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('SYSTEM_CONSTRAINT', 'CRITICAL', 'MEDIUM')]: 'PRESERVE',
+    [key('SYSTEM_CONSTRAINT', 'CRITICAL', 'LOW')]: 'PRESERVE',
+    // USER_CORRECTION — never touch
+    [key('USER_CORRECTION', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('USER_CORRECTION', 'CRITICAL', 'MEDIUM')]: 'PRESERVE',
+    [key('USER_CORRECTION', 'CRITICAL', 'LOW')]: 'PRESERVE',
+    // TASK_DEFINITION — preserve
+    [key('TASK_DEFINITION', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('TASK_DEFINITION', 'CRITICAL', 'MEDIUM')]: 'PRESERVE',
+    [key('TASK_DEFINITION', 'CRITICAL', 'LOW')]: 'PRESERVE',
+    // ERROR_ACTIVE — always preserve (current problem)
+    [key('ERROR_ACTIVE', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('ERROR_ACTIVE', 'CRITICAL', 'MEDIUM')]: 'PRESERVE',
+    [key('ERROR_ACTIVE', 'CRITICAL', 'LOW')]: 'PRESERVE',
+    // ERROR_RESOLVED — goldmine for savings
+    [key('ERROR_RESOLVED', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('ERROR_RESOLVED', 'HIGH', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('ERROR_RESOLVED', 'HIGH', 'MEDIUM')]: 'EXTRACT_RESULT',
+    [key('ERROR_RESOLVED', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('ERROR_RESOLVED', 'MEDIUM', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('ERROR_RESOLVED', 'MEDIUM', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('ERROR_RESOLVED', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('ERROR_RESOLVED', 'LOW', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('ERROR_RESOLVED', 'LOW', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('ERROR_RESOLVED', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('ERROR_RESOLVED', 'NEGLIGIBLE', 'HIGH')]: 'DROP',
+    [key('ERROR_RESOLVED', 'NEGLIGIBLE', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('ERROR_RESOLVED', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // TOOL_OUTPUT_STALE — second biggest savings source
+    [key('TOOL_OUTPUT_STALE', 'HIGH', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('TOOL_OUTPUT_STALE', 'HIGH', 'MEDIUM')]: 'EXTRACT_RESULT',
+    [key('TOOL_OUTPUT_STALE', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_STALE', 'MEDIUM', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('TOOL_OUTPUT_STALE', 'MEDIUM', 'MEDIUM')]: 'SUMMARIZE',
+    [key('TOOL_OUTPUT_STALE', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_STALE', 'LOW', 'HIGH')]: 'SUMMARIZE',
+    [key('TOOL_OUTPUT_STALE', 'LOW', 'MEDIUM')]: 'DEDUPLICATE',
+    [key('TOOL_OUTPUT_STALE', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_STALE', 'NEGLIGIBLE', 'HIGH')]: 'DROP',
+    [key('TOOL_OUTPUT_STALE', 'NEGLIGIBLE', 'MEDIUM')]: 'SUMMARIZE',
+    [key('TOOL_OUTPUT_STALE', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // TOOL_OUTPUT_ACTIVE — light touch only
+    [key('TOOL_OUTPUT_ACTIVE', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'HIGH', 'HIGH')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'HIGH', 'MEDIUM')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'MEDIUM', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('TOOL_OUTPUT_ACTIVE', 'MEDIUM', 'MEDIUM')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'LOW', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('TOOL_OUTPUT_ACTIVE', 'LOW', 'MEDIUM')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'NEGLIGIBLE', 'HIGH')]: 'SUMMARIZE',
+    [key('TOOL_OUTPUT_ACTIVE', 'NEGLIGIBLE', 'MEDIUM')]: 'PRESERVE',
+    [key('TOOL_OUTPUT_ACTIVE', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // REASONING_INTERMEDIATE
+    [key('REASONING_INTERMEDIATE', 'HIGH', 'HIGH')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'HIGH', 'MEDIUM')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'MEDIUM', 'HIGH')]: 'SUMMARIZE',
+    [key('REASONING_INTERMEDIATE', 'MEDIUM', 'MEDIUM')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'LOW', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('REASONING_INTERMEDIATE', 'LOW', 'MEDIUM')]: 'SUMMARIZE',
+    [key('REASONING_INTERMEDIATE', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('REASONING_INTERMEDIATE', 'NEGLIGIBLE', 'HIGH')]: 'DROP',
+    [key('REASONING_INTERMEDIATE', 'NEGLIGIBLE', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('REASONING_INTERMEDIATE', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // DECISION_FINAL
+    [key('DECISION_FINAL', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'HIGH', 'HIGH')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'HIGH', 'MEDIUM')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'MEDIUM', 'HIGH')]: 'EXTRACT_RESULT',
+    [key('DECISION_FINAL', 'MEDIUM', 'MEDIUM')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'LOW', 'HIGH')]: 'SUMMARIZE',
+    [key('DECISION_FINAL', 'LOW', 'MEDIUM')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'NEGLIGIBLE', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('DECISION_FINAL', 'NEGLIGIBLE', 'MEDIUM')]: 'PRESERVE',
+    [key('DECISION_FINAL', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // PROGRESS_MARKER
+    [key('PROGRESS_MARKER', 'HIGH', 'HIGH')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'HIGH', 'MEDIUM')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'MEDIUM', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('PROGRESS_MARKER', 'MEDIUM', 'MEDIUM')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'LOW', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('PROGRESS_MARKER', 'LOW', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('PROGRESS_MARKER', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('PROGRESS_MARKER', 'NEGLIGIBLE', 'HIGH')]: 'DROP',
+    [key('PROGRESS_MARKER', 'NEGLIGIBLE', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('PROGRESS_MARKER', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+    // CONVERSATIONAL — preserve recent turns; collapse only truly stale ones
+    [key('CONVERSATIONAL', 'CRITICAL', 'HIGH')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'HIGH', 'HIGH')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'HIGH', 'MEDIUM')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'HIGH', 'LOW')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'MEDIUM', 'HIGH')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'MEDIUM', 'MEDIUM')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'MEDIUM', 'LOW')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'LOW', 'HIGH')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'LOW', 'MEDIUM')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'LOW', 'LOW')]: 'PRESERVE',
+    [key('CONVERSATIONAL', 'NEGLIGIBLE', 'HIGH')]: 'COLLAPSE_TO_MARKER',
+    [key('CONVERSATIONAL', 'NEGLIGIBLE', 'MEDIUM')]: 'COLLAPSE_TO_MARKER',
+    [key('CONVERSATIONAL', 'NEGLIGIBLE', 'LOW')]: 'PRESERVE',
+};
+// ─── Escalation at Critical Threshold ────────────────────────────────────────
+function escalate(strategy, confidenceTier) {
+    if (confidenceTier === 'LOW')
+        return strategy;
+    const map = {
+        'PRESERVE': 'SUMMARIZE',
+        'SUMMARIZE': 'EXTRACT_RESULT',
+        'EXTRACT_RESULT': 'COLLAPSE_TO_MARKER',
+        'COLLAPSE_TO_MARKER': 'DROP',
+    };
+    return map[strategy] ?? strategy;
+}
+// ─── Selector ─────────────────────────────────────────────────────────────────
+function selectStrategy(message, utilizationPercent) {
+    // Pinned types are NEVER compressed or escalated, regardless of utilization
+    if ((0, classifier_1.isPinned)(message.classification))
+        return 'PRESERVE';
+    const confidenceTier = (0, confidence_1.getConfidenceTier)(message.classificationConfidence);
+    const relevanceTier = (0, scorer_1.scoreTierFromScore)(message.relevanceScore);
+    const tableKey = key(message.classification, relevanceTier, confidenceTier);
+    const base = STRATEGY_TABLE[tableKey] ?? 'PRESERVE';
+    if (utilizationPercent >= 0.80) {
+        return escalate(base, confidenceTier);
+    }
+    return base;
+}
+// ─── Batch ────────────────────────────────────────────────────────────────────
+function selectAllStrategies(messages, utilizationPercent) {
+    for (const message of messages) {
+        message.compressionStrategy = selectStrategy(message, utilizationPercent);
+    }
+    return messages;
+}

package/dist/src/tokenizer/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Exact token count using model-appropriate tokenizer.
+ * Falls back to character estimation if tokenizer unavailable.
+ */
+export declare function countTokens(text: string, model: string): Promise<number>;
+/**
+ * Fast approximate count — used only for UI/real-time displays.
+ * Never use this for compression decisions.
+ */
+export declare function estimate(text: string): number;
+/**
+ * Count tokens across an entire messages array.
+ */
+export declare function countMessagesTokens(messages: Array<{
+    role: string;
+    content: string | any[];
+}>, model: string): Promise<number>;
+export declare function getModelMaxTokens(model: string): number;