context_revive
Detect context pressure and restore capacity under GIA governance. Perform status, compact, verify, or history actions with tiered recommendations and mandatory gates.
Instructions
Governed context compaction — detects context pressure and restores capacity under GIA governance. Actions: status (health + recommendation), compact (execute compaction at tier), verify (integrity check on last compaction), history (compaction audit trail). Three tiers: sparkling (20-30%, INFORMATIONAL), electrolyte (40-55%, ADVISORY), iv (60-75%, MANDATORY gate). Force may override recommendation but NEVER bypasses MANDATORY gates. Cooldown prevents duplicate compaction per session+tier. No autonomous compaction loop.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform: status, compact, verify, or history | |
| session_id | No | Session ID (auto-detects or creates if omitted) | |
| tier | No | Compaction tier for compact action. Required for compact. | |
| force | No | Override tier recommendation (within policy bounds). Cannot bypass MANDATORY gates or cooldowns. |
Implementation Reference
- src/mcp/tools/context-revive.ts:222-637 (handler)The registerContextReviveTool function registers the 'context_revive' tool on the MCP server. The handler (inner async function from line 249-637) implements all four actions: status (health + recommendation), compact (execute compaction at tier with governance gates), verify (integrity check), and history (compaction audit trail). It uses the GovernanceEngine for gate enforcement, threshold monitoring, and ledger recording.
export function registerContextReviveTool(server: McpServer, engine: GovernanceEngine): void { server.tool( 'context_revive', 'Governed context compaction — detects context pressure and restores capacity under GIA governance. ' + 'Actions: status (health + recommendation), compact (execute compaction at tier), ' + 'verify (integrity check on last compaction), history (compaction audit trail). ' + 'Three tiers: sparkling (20-30%, INFORMATIONAL), electrolyte (40-55%, ADVISORY), iv (60-75%, MANDATORY gate). ' + 'Force may override recommendation but NEVER bypasses MANDATORY gates. ' + 'Cooldown prevents duplicate compaction per session+tier. No autonomous compaction loop.', { action: z.enum(['status', 'compact', 'verify', 'history']) .describe('Action to perform: status, compact, verify, or history'), session_id: z.string().optional() .describe('Session ID (auto-detects or creates if omitted)'), tier: z.enum(['sparkling', 'electrolyte', 'iv']).optional() .describe('Compaction tier for compact action. Required for compact.'), force: z.boolean().optional() .describe('Override tier recommendation (within policy bounds). Cannot bypass MANDATORY gates or cooldowns.'), }, { title: 'Context Revive — Governed Compaction', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false, } as Record<string, unknown>, async (args) => { const session = getOrCreateSession(args.session_id); // Refresh health from engine const health = computeHealthFromEngine(engine); session.healthGrade = health.grade; session.healthScore = health.score; session.fatigueState = health.fatigueState; session.budgetHealth = health.budgetHealth; session.tokensCurrent = health.tokensCurrent; session.tokensMax = health.tokensMax; switch (args.action) { // ─── STATUS ─────────────────────────────────────────────── case 'status': { const recommended = recommendTier(session.healthScore); const cooldownOk = recommended ? checkCooldown(session, recommended) : true; const status = { sessionId: session.sessionId, healthGrade: session.healthGrade, healthScore: session.healthScore, fatigueState: session.fatigueState, budgetHealth: session.budgetHealth, tokensCurrent: session.tokensCurrent, tokensMax: session.tokensMax, utilizationPercent: Math.round((session.tokensCurrent / session.tokensMax) * 100), recommendedTier: recommended, maiLevel: recommended ? MAI_MAPPING[recommended] : null, compactionAvailable: cooldownOk, cooldownExpiresAt: recommended && !cooldownOk ? getCooldownExpiry(session, recommended) : null, compactionCount: session.manifests.length, rationale: recommended ? `Health Grade ${session.healthGrade} (${session.healthScore}/100) — ${recommended} compaction recommended (${MAI_MAPPING[recommended]}). ` + `Target: ${(COMPRESSION_TARGETS[recommended].min * 100).toFixed(0)}-${(COMPRESSION_TARGETS[recommended].max * 100).toFixed(0)}% compression. ` + `Fatigue: ${session.fatigueState}. Budget: ${session.budgetHealth}.` : `Health Grade ${session.healthGrade} (${session.healthScore}/100) — no compaction needed.`, }; // Audit const entry = engine.ledger.begin( 'context_revive_status', MaiClassification.INFORMATIONAL, GiaLayer.MCP, 'context-revive' ); entry.addMetadata('sessionId', session.sessionId); entry.addMetadata('healthGrade', session.healthGrade); entry.addMetadata('recommendedTier', recommended || 'none'); const completed = entry.complete( engine.scorer.scoreDefault('context-revive'), { classification: MaiClassification.INFORMATIONAL, confidence: 1.0, rationale: 'Context revive status check — read-only', requiresGate: false, } ); engine.ledger.record(completed); return { content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2), }], }; } // ─── COMPACT ────────────────────────────────────────────── case 'compact': { const tier = args.tier; if (!tier) { return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'tier is required for compact action', validTiers: ['sparkling', 'electrolyte', 'iv'], }), }], }; } const force = args.force ?? false; const maiLevel = MAI_MAPPING[tier]; // Cooldown check — force cannot bypass if (!checkCooldown(session, tier)) { const expiry = getCooldownExpiry(session, tier); return { content: [{ type: 'text' as const, text: JSON.stringify({ blocked: true, reason: `Cooldown active for ${tier} tier. Cannot compact again until cooldown expires.`, cooldownExpiresAt: expiry, note: 'Cooldown prevents duplicate compaction and cannot be bypassed.', }), }], }; } // MANDATORY gate check for IV — force NEVER bypasses if (tier === 'iv') { try { const gateDecision = await engine.gate.enforce( MaiClassification.MANDATORY, 'context_revive_iv', `iv-revive-${session.sessionId}`, ); if (gateDecision.status !== GateStatus.APPROVED) { return { content: [{ type: 'text' as const, text: JSON.stringify({ blocked: true, reason: 'IV tier requires MANDATORY gate approval.', gateId: gateDecision.gateId, gateStatus: gateDecision.status, maiLevel: 'MANDATORY', action: 'Use approve_gate to approve this compaction, then retry.', note: 'force=true cannot bypass MANDATORY gates. This is a governance invariant.', }), }], }; } } catch (err: unknown) { const message = err instanceof Error ? err.message : String(err); return { content: [{ type: 'text' as const, text: JSON.stringify({ blocked: true, reason: `IV tier gate enforcement failed: ${message}`, maiLevel: 'MANDATORY', action: 'Gate was rejected or timed out. Use approve_gate to approve, then retry.', note: 'force=true cannot bypass MANDATORY gates. This is a governance invariant.', }), }], }; } } // Policy recommendation check const recommended = recommendTier(session.healthScore); if (!force && recommended === null) { return { content: [{ type: 'text' as const, text: JSON.stringify({ skipped: true, reason: `Health Grade ${session.healthGrade} (${session.healthScore}/100) — no compaction needed.`, hint: 'Use force=true to override recommendation (within policy bounds).', }), }], }; } // Execute compaction const tokensBefore = session.tokensCurrent; const target = COMPRESSION_TARGETS[tier]; const compressionRatio = (target.min + target.max) / 2; const tokensAfter = Math.round(tokensBefore * (1 - compressionRatio)); const manifestId = generateId(); const manifestData = JSON.stringify({ manifestId, sessionId: session.sessionId, tier, tokensBefore, tokensAfter, compressionRatio, force, }); const integrityHash = simpleHash(manifestData); const manifest: ReviveManifest = { manifestId, sessionId: session.sessionId, tier, maiLevel, executedAt: new Date().toISOString(), tokensBefore, tokensAfter, compressionRatio, packsAffected: [{ packId: `auto-${tier}-${Date.now().toString(36)}`, name: `${tier}-compaction-sweep`, tokensBefore, tokensAfter, action: 'compressed', }], integrityHash, forceOverride: force, healthGradeBefore: session.healthGrade, }; // Record session.manifests.push(manifest); if (session.manifests.length > MAX_MANIFEST_HISTORY) { session.manifests = session.manifests.slice(-MAX_MANIFEST_HISTORY); } session.lastCompaction[tier] = manifest.executedAt; session.tokensCurrent = tokensAfter; // Audit ledger const maiClass = tier === 'iv' ? MaiClassification.MANDATORY : tier === 'electrolyte' ? MaiClassification.ADVISORY : MaiClassification.INFORMATIONAL; const entry = engine.ledger.begin( 'context_revive_compact', maiClass, GiaLayer.MCP, 'context-revive' ); entry.addMetadata('manifestId', manifestId); entry.addMetadata('tier', tier); entry.addMetadata('tokensBefore', tokensBefore); entry.addMetadata('tokensAfter', tokensAfter); entry.addMetadata('compressionRatio', compressionRatio.toFixed(3)); entry.addMetadata('forceOverride', force); entry.addMetadata('healthGradeBefore', session.healthGrade); entry.addMetadata('integrityHash', integrityHash); const completed = entry.complete( engine.scorer.scoreDefault('context-revive-compact'), { classification: maiClass, confidence: 0.95, rationale: `Context revive ${tier} compaction — ${(compressionRatio * 100).toFixed(0)}% target compression${force ? ' (force override)' : ''}`, requiresGate: tier === 'iv', } ); engine.ledger.record(completed); return { content: [{ type: 'text' as const, text: JSON.stringify({ success: true, manifest: { manifestId: manifest.manifestId, tier: manifest.tier, maiLevel: manifest.maiLevel, tokensBefore: manifest.tokensBefore, tokensAfter: manifest.tokensAfter, compressionRatio: (manifest.compressionRatio * 100).toFixed(1) + '%', packsAffected: manifest.packsAffected.length, integrityHash: manifest.integrityHash, forceOverride: manifest.forceOverride, healthGradeBefore: manifest.healthGradeBefore, executedAt: manifest.executedAt, }, postCompaction: { tokensCurrent: session.tokensCurrent, tokensMax: session.tokensMax, utilizationPercent: Math.round((session.tokensCurrent / session.tokensMax) * 100), }, }, null, 2), }], }; } // ─── VERIFY ─────────────────────────────────────────────── case 'verify': { if (session.manifests.length === 0) { return { content: [{ type: 'text' as const, text: JSON.stringify({ verified: false, reason: 'No compaction manifests found for this session.', }), }], }; } const manifest = session.manifests[session.manifests.length - 1]; // Recompute hash const manifestData = JSON.stringify({ manifestId: manifest.manifestId, sessionId: manifest.sessionId, tier: manifest.tier, tokensBefore: manifest.tokensBefore, tokensAfter: manifest.tokensAfter, compressionRatio: manifest.compressionRatio, force: manifest.forceOverride, }); const recomputedHash = simpleHash(manifestData); const integrityHashValid = recomputedHash === manifest.integrityHash; const tokenReductionOccurred = manifest.tokensAfter < manifest.tokensBefore; const bounds = COMPRESSION_TARGETS[manifest.tier]; const compressionWithinBounds = manifest.compressionRatio >= bounds.min * 0.5 && manifest.compressionRatio <= bounds.max * 1.5; const verified = integrityHashValid && tokenReductionOccurred; // Audit const entry = engine.ledger.begin( 'context_revive_verify', MaiClassification.INFORMATIONAL, GiaLayer.MCP, 'context-revive' ); entry.addMetadata('manifestId', manifest.manifestId); entry.addMetadata('verified', verified); entry.addMetadata('integrityHashValid', integrityHashValid); const completed = entry.complete( engine.scorer.scoreDefault('context-revive-verify'), { classification: MaiClassification.INFORMATIONAL, confidence: 1.0, rationale: `Manifest verification: ${verified ? 'PASSED' : 'FAILED'}`, requiresGate: false, } ); engine.ledger.record(completed); return { content: [{ type: 'text' as const, text: JSON.stringify({ verified, manifestId: manifest.manifestId, checks: { manifestExists: true, integrityHashValid, tokenReductionOccurred, compressionWithinBounds, }, detail: verified ? `Manifest ${manifest.manifestId} verified: ${manifest.tier} tier, ${(manifest.compressionRatio * 100).toFixed(1)}% compression, integrity hash valid` : `Verification failed: hash=${integrityHashValid ? 'OK' : 'MISMATCH'}, reduction=${tokenReductionOccurred ? 'OK' : 'NONE'}`, }, null, 2), }], }; } // ─── HISTORY ────────────────────────────────────────────── case 'history': { const tierBreakdown: Record<string, number> = { sparkling: 0, electrolyte: 0, iv: 0, }; let totalTokensRecovered = 0; for (const m of session.manifests) { tierBreakdown[m.tier]++; totalTokensRecovered += m.tokensBefore - m.tokensAfter; } return { content: [{ type: 'text' as const, text: JSON.stringify({ sessionId: session.sessionId, totalCompactions: session.manifests.length, totalTokensRecovered, tierBreakdown, manifests: session.manifests.map(m => ({ manifestId: m.manifestId, tier: m.tier, maiLevel: m.maiLevel, executedAt: m.executedAt, tokensBefore: m.tokensBefore, tokensAfter: m.tokensAfter, compressionRatio: (m.compressionRatio * 100).toFixed(1) + '%', packsAffected: m.packsAffected.length, forceOverride: m.forceOverride, healthGradeBefore: m.healthGradeBefore, integrityHash: m.integrityHash, })), }, null, 2), }], }; } default: return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Unknown action: ${args.action}` }), }], }; } } - src/mcp/server.ts:118-118 (registration)Tool registration entry in server.ts at line 118: { tier: 'tenant', register: registerContextReviveTool, description: 'context_revive (status, compact, verify, history)' }. Imported at line 51.
{ tier: 'tenant', register: registerContextReviveTool, description: 'context_revive (status, compact, verify, history)' }, - Zod schema for the tool input: action (enum: status/compact/verify/history, required), session_id (optional string), tier (optional enum: sparkling/electrolyte/iv — required for compact), force (optional boolean — overrides recommendation but not MANDATORY gates).
{ action: z.enum(['status', 'compact', 'verify', 'history']) .describe('Action to perform: status, compact, verify, or history'), session_id: z.string().optional() .describe('Session ID (auto-detects or creates if omitted)'), tier: z.enum(['sparkling', 'electrolyte', 'iv']).optional() .describe('Compaction tier for compact action. Required for compact.'), force: z.boolean().optional() .describe('Override tier recommendation (within policy bounds). Cannot bypass MANDATORY gates or cooldowns.'), }, { title: 'Context Revive — Governed Compaction', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false, - Helper functions: simpleHash (string hash), generateId (unique IDs), recommendTier (maps health score to compaction tier), checkCooldown/getCooldownExpiry (cooldown enforcement, 120s), getOrCreateSession (session management), computeHealthFromEngine (pulls real-time health from GovernanceEngine).
function simpleHash(data: string): string { let hash = 0; for (let i = 0; i < data.length; i++) { const char = data.charCodeAt(i); hash = ((hash << 5) - hash) + char; hash = hash & hash; } return Math.abs(hash).toString(16).padStart(8, '0'); } function generateId(): string { return `revive-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`; } function recommendTier(score: number): ReviveTier | null { if (score <= TIER_THRESHOLDS.iv) return 'iv'; if (score <= TIER_THRESHOLDS.electrolyte) return 'electrolyte'; if (score <= TIER_THRESHOLDS.sparkling) return 'sparkling'; return null; } function checkCooldown(session: ReviveSession, tier: ReviveTier): boolean { const lastTime = session.lastCompaction[tier]; if (!lastTime) return true; const elapsed = (Date.now() - new Date(lastTime).getTime()) / 1000; return elapsed >= COOLDOWN_SECONDS; } function getCooldownExpiry(session: ReviveSession, tier: ReviveTier): string | null { const lastTime = session.lastCompaction[tier]; if (!lastTime) return null; const expiresAt = new Date(lastTime).getTime() + (COOLDOWN_SECONDS * 1000); return new Date(expiresAt).toISOString(); } function getOrCreateSession(sessionId?: string): ReviveSession { // If session ID provided and exists, return it if (sessionId && reviveSessions.has(sessionId)) { return reviveSessions.get(sessionId)!; } // Auto-create or return first session if (!sessionId) { const existing = Array.from(reviveSessions.values()); if (existing.length > 0) return existing[0]; sessionId = generateId(); } const session: ReviveSession = { sessionId, startedAt: new Date().toISOString(), manifests: [], lastCompaction: {}, tokensCurrent: 0, tokensMax: parseInt(process.env.CONTEXT_REVIVE_MAX_TOKENS ?? '200000', 10), healthGrade: 'A', healthScore: 100, fatigueState: 'STABLE', budgetHealth: 'HEALTHY', }; reviveSessions.set(sessionId, session); return session; } - Constants: MAI_MAPPING (tier to MAI level: sparkling=INFORMATIONAL, electrolyte=ADVISORY, iv=MANDATORY), COMPRESSION_TARGETS (tier compression ratios), TIER_THRESHOLDS (health score thresholds for each tier), COOLDOWN_SECONDS (120), MAX_MANIFEST_HISTORY (50).
const MAI_MAPPING: Record<ReviveTier, ReviveMaiLevel> = { sparkling: 'INFORMATIONAL', electrolyte: 'ADVISORY', iv: 'MANDATORY', }; const COMPRESSION_TARGETS: Record<ReviveTier, { min: number; max: number }> = { sparkling: { min: 0.20, max: 0.30 }, electrolyte: { min: 0.40, max: 0.55 }, iv: { min: 0.60, max: 0.75 }, };