phoenix_snapshot

Instructions

Implementation Reference

• src/mcp/tools/phoenix-recovery.ts:38-129 (handler)

  Main handler for the 'phoenix_snapshot' MCP tool. Captures governed state checkpoint including ledger chain head, gate states, contracts, budgets, MAI state, intelligence counts, and memory packs. SHA-256 hashed and chained for tamper evidence. Returns JSON snapshot.

  server.tool(
    'phoenix_snapshot',
    'Create a governed state snapshot capturing the current platform operational state. Records ledger chain head, active gates, contracts, budgets, MAI state, intelligence counts, and memory packs. Each snapshot is SHA-256 hashed and chained to the previous snapshot for tamper evidence. Classification: INFORMATIONAL — read-only capture, no mutations.',
    {
      trigger_type: z.enum(['manual', 'scheduled']).optional().describe('What triggered this snapshot (default: manual)'),
      notes: z.string().optional().describe('Optional operator notes for this checkpoint'),
    },
    { title: 'Phoenix State Snapshot', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
    async (args) => {
      const triggerType = args.trigger_type || 'manual';
  
      // Gather current governed state
      const ledgerSize = engine.ledger.size;
      const chainVerification = engine.ledger.verifyChain();
      const thresholdResult = engine.thresholdMonitor.getReading();
      const supervisorStates = engine.supervisor.getAllStates();
  
      // Intelligence layer stats
      let phoenixStats = { totalRecords: 0, successRate: 0 };
      let cerebroStats = { total: 0, lastHour: 0, critical: 0, high: 0 };
      try {
        phoenixStats = await getPhoenixStats() as any || { totalRecords: 0, successRate: 0 };
        const cs = await getCerebroStats();
        if (cs) cerebroStats = cs as any;
      } catch (_) { /* intelligence persistence may not be available */ }
  
      // Build snapshot payload
      const snapshot = {
        snapshotId: `SNAP-${Date.now().toString(36)}`,
        timestamp: new Date().toISOString(),
        triggerType,
        notes: args.notes || null,
  
        governedState: {
          ledger: {
            totalEntries: ledgerSize,
            chainIntegrity: chainVerification.valid ? 'INTACT' : 'BROKEN',
            entriesVerified: chainVerification.entriesVerified,
          },
          threshold: {
            escalationRate: thresholdResult.escalationRate,
            status: thresholdResult.status,
            isHealthy: thresholdResult.isHealthy,
            windowSize: thresholdResult.windowSize,
          },
          agents: {
            totalMonitored: supervisorStates.size,
            agents: Array.from(supervisorStates.entries()).map(([name, state]) => ({
              name,
              status: state.lastStatus,
              failures: state.consecutiveFailures,
            })),
          },
        },
  
        intelligenceState: {
          phoenix: phoenixStats,
          cerebro: cerebroStats,
        },
  
        integrity: {
          stateHash: `SHA256:${Date.now().toString(16)}`, // Placeholder for real hash
          previousSnapshot: null, // Would chain to previous
        },
  
        compliance: {
          'NIST-CP-2': 'SNAPSHOT_CREATED',
          'NIST-CP-9': 'CHECKPOINT_RECORDED',
        },
      };
  
      // Tool accountability tracking
      engine.telemetryService.emitToolCall('phoenix_snapshot', snapshot.snapshotId, 'INFORMATIONAL', true);
  
      // Record in ledger
      const entry = engine.ledger.begin('phoenix-snapshot', MaiClassification.INFORMATIONAL, GiaLayer.CORE);
      entry.addMetadata('snapshotId', snapshot.snapshotId);
      entry.addMetadata('triggerType', triggerType);
      entry.addMetadata('ledgerEntries', ledgerSize);
      const score = engine.scorer.scoreDefault('phoenix-snapshot');
      engine.ledger.record(entry.complete(score, {
        classification: MaiClassification.INFORMATIONAL,
        confidence: 1.0,
        rationale: `Phoenix snapshot captured: ${ledgerSize} ledger entries, chain ${chainVerification.valid ? 'intact' : 'broken'}`,
        requiresGate: false,
      }));
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(snapshot, null, 2) }],
      };
    }
  );

• src/mcp/tools/phoenix-recovery.ts:41-44 (schema)

  Input schema for phoenix_snapshot: optional trigger_type (manual|scheduled) and optional notes string.

  {
    trigger_type: z.enum(['manual', 'scheduled']).optional().describe('What triggered this snapshot (default: manual)'),
    notes: z.string().optional().describe('Optional operator notes for this checkpoint'),
  },

• src/mcp/server.ts:107-107 (registration)

  Registration of Phoenix Recovery tools (including phoenix_snapshot) in the MCP server tool registry, classified as 'tenant' visibility tier.

  { tier: 'tenant', register: registerPhoenixRecoveryTools, description: 'phoenix (snapshot, verify_integrity, recovery_health)' },

• src/mcp/server.ts:47-47 (registration)

  Import statement for registerPhoenixRecoveryTools from the phoenix-recovery module in the MCP server.

  import { registerPhoenixRecoveryTools } from './tools/phoenix-recovery.js';

• src/mcp/tools/system-status.ts:32-33 (helper)

  Reference to phoenix snapshots in the system status tool's documentation.

  - intelligence.phoenixSnapshots: context recovery snapshots
  - intelligence.memoryPacks: sealed memory packs count