Plan Types Reference

interface ExecutionPlan {
  /** Unique identifier for the plan */
  id: string;
  
  /** What the user is trying to accomplish */
  goal: string;
  
  /** Current status of the plan */
  status: PlanStatus;
  
  /** All steps in the plan */
  steps: ExecutionStep[];
  
  /** Number of completed steps */
  completed_steps: number;
  
  /** Total number of steps */
  total_steps: number;
  
  /** Whether the plan should auto-execute */
  auto_execute: boolean;
  
  /** Timestamp when created */
  created_at: string;
  
  /** Timestamp when last updated */
  updated_at: string;
}

type PlanStatus =
  | 'awaiting_start'   // User must click "Start" to begin
  | 'executing'        // Plan is running
  | 'awaiting_result'  // Waiting for step completion
  | 'completed'        // All steps finished
  | 'cancelled'        // User cancelled the plan
  | 'failed';          // A step failed

interface ExecutionStep {
  /** Unique identifier for the step */
  id: string;
  
  /** Step order (0-indexed) */
  index: number;
  
  /** Human-readable description */
  description: string;
  
  /** Action to execute */
  action_name: string;
  
  /** Data to pass to the action */
  action_data: Record<string, unknown>;
  
  /** Current status */
  status: StepStatus;
  
  /** Execute without user clicking */
  auto_run: boolean;
  
  /** Mark done immediately after executing */
  auto_complete: boolean;
  
  /** Pause for user confirmation before executing */
  requires_user_confirmation: boolean;
}

type StepStatus =
  | 'pending'    // Not yet reached
  | 'active'     // Currently active
  | 'completed'  // Successfully finished
  | 'skipped'    // User skipped this step
  | 'failed';    // Step failed

const { activePlan } = usePillar();

if (activePlan) {
  console.log(`Working on: ${activePlan.goal}`);
  console.log(`Progress: ${activePlan.completed_steps}/${activePlan.total_steps}`);
}

await pillar.startPlan();

// Use completeAction() - works for both standalone and plan steps
await pillar.completeAction('add_source', true, { sourceId: '123' });

// Or by step ID (for custom UI)
await pillar.markPlanStepDone(stepId);

await pillar.skipPlanStep(stepId);

await pillar.cancelPlan();