Undo For Agents: Building Reversible Voice Actions With Checkpoints

class CheckpointManager {
  constructor() {
    this.checkpoints = new Map();
    this.maxCheckpoints = 10; // Keep last 10 actions
  }
  
  async createCheckpoint(actionId, stateType, currentState) {
    const checkpoint = {
      id: actionId,
      timestamp: Date.now(),
      stateType: stateType,
      snapshot: await this.captureState(stateType, currentState),
      metadata: {
        user_id: currentState.user_id,
        action_description: currentState.description
      }
    };
    
    this.checkpoints.set(actionId, checkpoint);
    
    // Cleanup old checkpoints
    if (this.checkpoints.size > this.maxCheckpoints) {
      const oldest = Array.from(this.checkpoints.keys())[0];
      this.checkpoints.delete(oldest);
    }
    
    console.log(`✓ Checkpoint created: ${actionId}`);
    return checkpoint;
  }
  
  async captureState(stateType, currentState) {
    // Deep clone state based on type
    switch(stateType) {
      case 'database':
        return await this.snapshotDatabase(currentState);
        
      case 'file':
        return await this.snapshotFile(currentState);
        
      case 'workspace':
        return await this.snapshotWorkspace(currentState);
        
      case 'cart':
        return await this.snapshotCart(currentState);
        
      default:
        return JSON.parse(JSON.stringify(currentState));
    }
  }
  
  async snapshotDatabase(state) {
    // For database modifications, store the query to reverse it
    return {
      type: 'database',
      table: state.table,
      operation: state.operation,
      record_id: state.record_id,
      previous_values: await db.query(
        `SELECT * FROM ${state.table} WHERE id = ?`,
        [state.record_id]
      )
    };
  }
  
  async snapshotFile(state) {
    // For files, store content before modification
    return {
      type: 'file',
      path: state.path,
      content: await fs.readFile(state.path, 'utf8'),
      metadata: await fs.stat(state.path)
    };
  }
  
  async snapshotWorkspace(state) {
    // For workspace, store full structure
    return {
      type: 'workspace',
      workspace_id: state.workspace_id,
      structure: await workspace.export(state.workspace_id),
      timestamp: Date.now()
    };
  }
  
  async snapshotCart(state) {
    // For shopping cart, store items and quantities
    return {
      type: 'cart',
      user_id: state.user_id,
      items: [...state.items], // Deep copy
      total: state.total
    };
  }
  
  async rollback(actionId) {
    const checkpoint = this.checkpoints.get(actionId);
    
    if (!checkpoint) {
      throw new Error(`Checkpoint ${actionId} not found`);
    }
    
    console.log(`⏮️  Rolling back: ${actionId}`);
    await this.restoreState(checkpoint);
    
    return checkpoint;
  }
  
  async restoreState(checkpoint) {
    switch(checkpoint.stateType) {
      case 'database':
        await this.restoreDatabase(checkpoint.snapshot);
        break;
        
      case 'file':
        await this.restoreFile(checkpoint.snapshot);
        break;
        
      case 'workspace':
        await this.restoreWorkspace(checkpoint.snapshot);
        break;
        
      case 'cart':
        await this.restoreCart(checkpoint.snapshot);
        break;
    }
  }
  
  async restoreDatabase(snapshot) {
    // Restore previous database values
    await db.query(
      `UPDATE ${snapshot.table} SET ? WHERE id = ?`,
      [snapshot.previous_values, snapshot.record_id]
    );
  }
  
  async restoreFile(snapshot) {
    // Restore previous file content
    await fs.writeFile(snapshot.path, snapshot.content, 'utf8');
    await fs.utimes(snapshot.path, snapshot.metadata.atime, snapshot.metadata.mtime);
  }
  
  async restoreWorkspace(snapshot) {
    // Restore workspace structure
    await workspace.import(snapshot.workspace_id, snapshot.structure);
  }
  
  async restoreCart(snapshot) {
    // Restore cart items
    await cart.replace(snapshot.user_id, snapshot.items);
  }
}

class ReversibleAction {
  constructor(checkpointManager) {
    this.checkpoints = checkpointManager;
    this.activeActions = new Map();
  }
  
  async execute(action) {
    const actionId = this.generateActionId();
    
    try {
      // Step 1: Create checkpoint
      const checkpoint = await this.checkpoints.createCheckpoint(
        actionId,
        action.stateType,
        action.currentState
      );
      
      // Step 2: Execute action
      console.log(`▶️  Executing: ${action.description}`);
      const result = await action.handler();
      
      // Step 3: Validate result
      const validation = await this.validateResult(result, action);
      
      if (!validation.safe) {
        // Auto-rollback if validation fails
        console.log(`⚠️  Validation failed: ${validation.reason}`);
        await this.checkpoints.rollback(actionId);
        
        return {
          success: false,
          rolled_back: true,
          reason: validation.reason,
          checkpoint: checkpoint.id
        };
      }
      
      // Step 4: Commit (mark as successful)
      this.activeActions.set(actionId, {
        checkpoint: checkpoint.id,
        action: action,
        result: result,
        timestamp: Date.now()
      });
      
      return {
        success: true,
        result: result,
        actionId: actionId,
        undo_available: true
      };
      
    } catch (error) {
      // Auto-rollback on error
      console.error(`❌ Error executing action: ${error.message}`);
      await this.checkpoints.rollback(actionId);
      
      throw error;
    }
  }
  
  async validateResult(result, action) {
    // Run validation checks
    const checks = action.validations || [];
    
    for (const check of checks) {
      const valid = await check(result);
      if (!valid.passed) {
        return {
          safe: false,
          reason: valid.reason
        };
      }
    }
    
    return { safe: true };
  }
  
  async undo(actionId) {
    const action = this.activeActions.get(actionId);
    
    if (!action) {
      throw new Error(`Cannot undo: action ${actionId} not found`);
    }
    
    // Rollback to checkpoint
    await this.checkpoints.rollback(action.checkpoint);
    
    // Remove from active actions
    this.activeActions.delete(actionId);
    
    console.log(`✓ Undone: ${action.action.description}`);
    
    return {
      undone: true,
      action: action.action.description
    };
  }
  
  async undoLast() {
    // Undo most recent action
    const lastActionId = Array.from(this.activeActions.keys()).pop();
    
    if (lastActionId) {
      return await this.undo(lastActionId);
    }
    
    throw new Error('No actions to undo');
  }
  
  generateActionId() {
    return `action_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }
}

const checkpointManager = new CheckpointManager();
const reversibleActions = new ReversibleAction(checkpointManager);

const voiceAgent = {
  model: "gpt-realtime",
  tools: [
    {
      type: "function",
      name: "delete_project",
      description: "Delete a project. This action is reversible.",
      parameters: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project identifier" },
          project_name: { type: "string", description: "Project name for confirmations" }
        },
        required: ["project_id", "project_name"]
      }
    },
    {
      type: "function",
      name: "undo_last_action",
      description: "Undo the most recent reversible action.",
      parameters: {
        type: "object",
        properties: {}
      }
    }
  ],

  instructions: `You are a helpful assistant with undo capabilities.
  
  When users take actions that modify data:
  1. Execute the action (it's automatically checkpointed)
  2. Confirm what you did: "Done - I've deleted that project"
  3. Remind them they can undo: "If you need to undo this, just say 'undo that'"
  
  When users say "undo", "undo that", "go back", or "revert":
  - Call the undoLastAction tool
  - Confirm what was undone: "Undone - I've restored that project"
  `
};

async executeDangerousAction(action, client) {
  if (action.high_risk) {
    // Ask for confirmation first through the agent's response
    // The agent will naturally ask and wait for user response
    // This is handled through the conversation flow
    
    // Return action details for agent to confirm
    return {
      requires_confirmation: true,
      confirmation_message: `Just to confirm: you want me to ${action.description}? ` +
        `Say 'yes' to proceed or 'cancel' to stop.`,
      action: action,
      // Execute only after user confirms in conversation
      onConfirm: async () => {
        return await reversibleActions.execute(action);
      }
    };
  }
  
  // Low-risk actions proceed immediately with undo option
  return await reversibleActions.execute(action);
}

async undoSpecific(description) {
  // Find action matching description
  const actions = Array.from(this.activeActions.entries());
  
  const match = actions.find(([id, action]) => 
    action.action.description.toLowerCase().includes(description.toLowerCase())
  );
  
  if (match) {
    return await this.undo(match[0]);
  }
  
  throw new Error(`No action found matching: ${description}`);
}

class SafeReversibleAction extends ReversibleAction {
  async execute(action) {
    const actionId = this.generateActionId();
    
    // Create checkpoint
    const checkpoint = await this.checkpoints.createCheckpoint(
      actionId,
      action.stateType,
      action.currentState
    );
    
    // Execute action
    const result = await action.handler();
    
    // Check guardrails
    const guardrailCheck = await this.checkGuardrails(result, action);
    
    if (guardrailCheck.violated) {
      // AUTO-ROLLBACK on guardrail violation
      console.log(`🛑 Guardrail violation: ${guardrailCheck.policy}`);
      await this.checkpoints.rollback(actionId);
      
      // Explain to user
      await agent.speak(
        `I started that action but stopped it because ${guardrailCheck.reason}. ` +
        `Everything has been restored to how it was before.`
      );
      
      return {
        success: false,
        rolled_back: true,
        reason: guardrailCheck.reason
      };
    }
    
    // Commit if safe
    this.activeActions.set(actionId, {
      checkpoint: checkpoint.id,
      action: action,
      result: result
    });
    
    return {
      success: true,
      result: result,
      actionId: actionId
    };
  }
  
  async checkGuardrails(result, action) {
    // Run safety checks
    const policies = action.guardrails || [];
    
    for (const policy of policies) {
      const check = await policy(result);
      if (check.violated) {
        return {
          violated: true,
          policy: policy.name,
          reason: check.reason
        };
      }
    }
    
    return { violated: false };
  }
}

tools: [
  {
    type: "function",
    name: "update_pricing",
    description: "Update product pricing with guardrails and auto-rollback.",
    parameters: {
      type: "object",
      properties: {
        product: { type: "string", description: "Product name" },
        product_id: { type: "string", description: "Product identifier" },
        old_price: { type: "number", description: "Current price" },
        new_price: { type: "number", description: "Requested new price" }
      },
      required: ["product_id", "old_price", "new_price"]
    }
  }
]

const toolHandlers = {
  update_pricing: async (params) => {
    return safeReversibleActions.execute({
      description: `Update pricing for ${params.product}`,
      stateType: 'database',
      currentState: { table: 'products', record_id: params.product_id },
      handler: async () => db.products.update(params.product_id, { price: params.new_price }),
      guardrails: [
        async () => (
          params.new_price > params.old_price * 2
            ? { violated: true, reason: "price increase exceeds 100% - likely a mistake" }
            : { violated: false }
        ),
        async () => (
          params.new_price < 1.0
            ? { violated: true, reason: "price below minimum threshold" }
            : { violated: false }
        )
      ]
    });
  }
};

async cleanupExpiredCheckpoints() {
  const now = Date.now();
  const TTL = 60 * 60 * 1000; // 1 hour
  
  for (const [id, checkpoint] of this.checkpoints.entries()) {
    if (now - checkpoint.timestamp > TTL) {
      this.checkpoints.delete(id);
      console.log(`🗑️  Expired checkpoint: ${id}`);
    }
  }
}

// Run cleanup periodically
setInterval(() => this.cleanupExpiredCheckpoints(), 5 * 60 * 1000);

async rollback(actionId) {
  const checkpoint = this.checkpoints.get(actionId);
  
  // Check if state changed since checkpoint
  const currentState = await this.getCurrentState(checkpoint.stateType);
  const conflict = await this.detectConflict(checkpoint.snapshot, currentState);
  
  if (conflict) {
    throw new Error(
      `Cannot undo: state has changed since action was taken. ` +
      `Conflict: ${conflict.reason}`
    );
  }
  
  await this.restoreState(checkpoint);
}

async confirmAction(action, result) {
  if (result.undo_available) {
    await agent.speak(
      `${action.confirmation_message} ` +
      `If you need to undo this, just say "undo that".`
    );
  } else {
    await agent.speak(action.confirmation_message);
  }
}