Advisor Action Framework

Instructions

Implement the propose-confirm-execute-verify pattern for AI advisors that can take real-world actions on behalf of users. Safety, transparency, and reversibility are the core principles.

Action Lifecycle

Every advisor action follows a four-phase lifecycle:

PROPOSE → CONFIRM → EXECUTE → VERIFY
   ↑                            |
   └──── ROLLBACK ←─────────────┘ (if verification fails)

1. Propose: The AI advisor identifies an action and presents it with full context
2. Confirm: The user reviews and explicitly approves, modifies, or rejects
3. Execute: The system performs the action via the appropriate integration
4. Verify: The system confirms the action completed as expected

Action Proposal Schema

Every proposed action must include:

interface ActionProposal {
  action_id: string;          // UUID for tracking
  action_type: string;        // e.g., "calendar.create_event", "email.send", "task.create"
  summary: string;            // Human-readable one-line description
  details: {
    service: string;          // Target service (Google Calendar, Gmail, Todoist, etc.)
    operation: string;        // CRUD operation
    parameters: Record<string, any>;  // Service-specific parameters
  };
  reversible: boolean;        // Can this action be undone?
  rollback_strategy?: string; // How to undo if reversible
  impact_level: 'low' | 'medium' | 'high';  // Guides confirmation UX
  confidence: number;         // 0.0–1.0: advisor's confidence this is the right action
  reasoning: string;          // Why the advisor is proposing this action
  alternatives?: ActionProposal[];  // Other actions the advisor considered
}

Impact Level Classification

Level	Criteria	Confirmation UX	Examples
Low	Reversible, no external recipients, low cost	Single tap/click to confirm	Creating a draft, adding a task, bookmarking
Medium	Involves external parties or moderate commitment	Review details + confirm button	Sending an email, creating a calendar event with attendees
High	Irreversible, financial impact, or broad reach	Explicit typed confirmation or multi-step review	Sending a payment, publishing content, deleting data

Confirmation Patterns

Inline confirmation: For low-impact actions, show the proposal inline in the chat with Accept/Reject buttons.

Detail review: For medium-impact actions, expand a card showing all parameters the user can edit before confirming.

Explicit confirmation: For high-impact actions, require the user to type a confirmation phrase or complete a multi-step review.

Batch confirmation: When the advisor proposes multiple related actions (e.g., “create 5 calendar events for this trip”), allow batch review with per-item accept/reject.

Auto-execute rules: Users can configure rules for automatic execution without confirmation:

• Only for low impact actions
• Only for specific action types the user has pre-approved
• Always log auto-executed actions for later review
• User can revoke auto-execute permission at any time

Execution Engine

• Execute actions through the appropriate service integration (MCP tool call, REST API, local operation)
• Set a timeout per action type — do not hang indefinitely on a failed API call
• Capture the full response from the service for verification
• If execution fails, return the error to the user with context, do not silently retry

Verification

After execution, verify the outcome:

• Positive verification: Confirm the action produced the expected result (e.g., event appears on calendar, email is in sent folder)
• Negative verification: Check for unintended side effects (e.g., duplicate events, wrong recipients)
• Deferred verification: Some actions can only be verified later (e.g., “did the recipient respond?”) — schedule a follow-up check

Report verification results to the user:

✓ Created event "Team Standup" on April 15, 10:00 AM – 10:30 AM
  Attendees: alice@example.com, bob@example.com
  Calendar: Work

Rollback Capability

For reversible actions, implement rollback:

• Store the pre-action state or the inverse operation needed to undo
• Rollback must be available for at least 24 hours after execution
• Present rollback as an “Undo” option in the verification confirmation
• Log rollback operations with the same audit trail as forward operations

Audit Logging

Every action lifecycle event must be logged:

interface ActionAuditEntry {
  timestamp: string;         // ISO 8601
  action_id: string;         // Links to the proposal
  phase: 'proposed' | 'confirmed' | 'rejected' | 'executed' | 'verified' | 'rolled_back' | 'failed';
  actor: 'advisor' | 'user' | 'system';
  details: Record<string, any>;  // Phase-specific details
  duration_ms?: number;      // Execution time for execute/verify phases
}

• Store audit logs in the local SQLite database
• Audit logs are append-only — never delete or modify entries
• Provide a UI for users to review their action history
• Include the advisor’s reasoning in the proposal audit entry

Multi-Action Orchestration

When a user request requires multiple actions:

1. Plan: Generate the full sequence of actions with dependencies
2. Present: Show the plan as an ordered list with dependency arrows
3. Confirm: Allow batch or per-step confirmation
4. Execute sequentially: Run actions in dependency order, stopping on failure
5. Partial rollback: If action 3 of 5 fails, offer to roll back actions 1 and 2

Safety Guardrails

• Never execute a high impact action without explicit user confirmation, regardless of auto-execute rules
• Rate-limit action execution: no more than 10 actions per minute, 100 per hour
• Detect and prevent duplicate actions: if an identical action was executed in the last 5 minutes, warn before re-executing
• Disallow actions that would delete all items in a collection without special confirmation

Inputs Required

• User request or advisor-initiated suggestion triggering the action
• Target service credentials and connection status
• User’s auto-execute preferences and confirmation settings
• Previous action history for duplicate detection

Output Format

• Action proposal with summary, details, impact level, and reasoning
• Confirmation UI appropriate to the impact level
• Execution result with success/failure status
• Verification report confirming the action outcome
• Audit log entry for each lifecycle phase
• Rollback option for reversible actions

Anti-Patterns

• Executing without confirmation: Never skip confirmation for medium or high impact actions — this erodes user trust
• Opaque action proposals: “I’ll handle that” is not a proposal — always show exactly what will be done, to which service, with which parameters
• No rollback path: If an action is reversible, implement the rollback — telling users “you can undo it manually” is not acceptable
• Silent failures: If execution fails, the user must know immediately — do not silently retry or swallow errors
• Unbounded auto-execution: Auto-execute rules must be scoped, rate-limited, and revocable — an AI agent with unlimited auto-execute capability is a liability
• Missing audit trail: Every action must be logged — skipping audit logging for “minor” actions creates accountability gaps